Skip to main content

Configuration

Configuration in ggshield follows a global > local > CLI configuration scheme.

Meaning options on local overwrite or extend global and options on CLI overwrite or extend local.

Configuration file#

gg-shield will search for a global config file in the user's home directory (example: ~/.gitguardian.yml on Linux and %USERPROFILE%\.gitguardian on Windows).

gg-shield will recognize a local config file in the user's working directory as well (example: ./.gitguardian.yml).

You can also use the option --config-path on the main command to set another config file. In this case, neither local nor global config files will be evaluated (example: ggshield --config-path=~/Desktop/only_config.yaml scan path -r .)

A sample config file can be found at .gitguardian.example

# Exclude files and paths by globbingpaths-ignore:  - '**/README.md'  - 'doc/*'  - 'LICENSE'
# Ignore policy breaks with the SHA256 of the policy break obtained at output or the secret itselfmatches-ignore:  - name:    matches: 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1  - name: credentials    matches: MY_TEST_CREDENTIAL
show-secrets: false # default: false
# Set to true if the desired exit code for the CLI is always 0,# otherwise the exit code will be 1 if incidents are found.# the environment variable GITGUARDIAN_EXIT_ZERO=true can also be used toggle this behaviour.exit-zero: false # default: false
# By default only secrets are detected. Use all-policies to toggle this behaviour.all-policies: false # default: false
api-url: https://api.gitguardian.com # GITGUARDIAN_API_URL environment variable will override this setting
verbose: false # default: false

Note: Old configurations of matches-ignore with a list of secrets instead of composite entries are deprecated but still supported:

# Ignore policy breaks with the SHA256 of the policy break obtained at output or the secret itselfmatches-ignore: - 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1 - MY_TEST_CREDENTIAL

Environment Variables#

Some configurations on gg-shield can be done through environment variables. Environment variables will override settings set on your config file but will be overridden by command line options.

GITGUARDIAN_API_KEY: [Required] API Key for the GitGuardian API.
GITGUARDIAN_API_URL: Custom URL for the scanning API. Default  "https://api.gitguardian.com/v1"
GITGUARDIAN_DONT_LOAD_ENV: If set to any value environment variables won't be loaded from a file.
GITGUARDIAN_DOTENV_PATH: If set to a path, `gg-shield` will attempt to load the environment from the specified file.

At startup, gg-shield will attempt to load environment variables from different environment files in the following order:

  • path pointed to by the environment variable GITGUARDIAN_DOTENV_PATH
  • .env at your current work directory.
  • .env at the root of the current git directory

Only one file will be loaded out of the three.

Ignore list#

Useful for ignoring a revoked test credential or a false positive, there are different ways to ignore a secret with gg-shield.

  • using the ignore command to ignore the latest secrets found in your scan.
  • adding the ignore SHA that accompanies the incident or one of the secret matches to the configuration file
  • directly in code by suffixing the line with a ggignore comment.

Examples:

def send_to_notifier() -> int:  return send_slack_message(token="xoxb-23s2js9912ksk120wsjp") # ggignore
func main() {  high_entropy_test := "A@@E*JN#DK@OE@K(JEN@I@#)" // ggignore}

Note that this ggignore comment will also ignore the secret in your GitGuardian dashboard.

On-premise configuration#

gg-shield can be configured to run on your on-premise GitGuardian instance.

You can modify your environment variables to include:

GITGUARDIAN_API_KEY=<GitGuardian API Key>GITGUARDIAN_API_URL=<GitGuardian on-premises API URL>

Your GITGUARDIAN_API_KEY will usually be https://${your_hostname}/exposed/.

Alternatively to setting the GITGUARDIAN_API_URL environment variable, set the api-url in your .gitguardian.yaml.