GitGuardian

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Introduced in GitLab 16.9 with a flag named git_guardian_integration. Enabled by default. Disabled on GitLab.com.
• Enabled on GitLab.com in GitLab 17.7.
• Generally available in GitLab 17.8. Feature flag git_guardian_integration removed.
• api_url parameter introduced in GitLab 19.1.

{{< /history >}}

GitGuardian is a secrets detection service that finds hardcoded credentials such as API keys, passwords, and tokens in source code repositories. When you enable this integration, GitLab sends each push to GitGuardian for scanning. If GitGuardian detects a secret, GitLab blocks the push.

You can configure GitLab to reject commits based on GitGuardian policies.

To set up the GitGuardian integration:

1. Create a GitGuardian API token.
2. Set up the GitGuardian integration for your project.

Create a GitGuardian API token

Prerequisites:

• You must have a GitGuardian account.

To create an API token:

1. Sign in to your GitGuardian account.
2. Go to the API section in the sidebar.
3. In the API section sidebar go to Personal access tokens page.
4. Select Create token. The token creation dialog opens.
5. Provide your token information:
   • Give your API token a meaningful name to identify its purpose. For example, GitLab integration token.
   • Select an appropriate expiration.
   • Select the scan scope checkbox. It is the only one needed for the integration.
6. Select Create token.
7. After you've generated a token, copy it to your clipboard. This token is sensitive information, so keep it secure.

Now you have successfully created a GitGuardian API token that you can use to for our integration.

Set up the GitGuardian integration for your project

Prerequisites:

• You must have the Maintainer or Owner role for the project.

After you have created and copied your API token, configure GitLab to reject commits:

To enable the integration for your project:

1. In the top bar, select Search or go to and find your project or group.

2. In the left sidebar, select Settings > Integrations.

3. Select GitGuardian.

4. In Enable integration, select the Active checkbox.

5. Optional. In the API endpoint text box, enter the base URL of your GitGuardian instance:

   • For GitGuardian EU SaaS, enter https://api.eu1.gitguardian.com.
   • For self-hosted GitGuardian, enter your instance URL (for example, https://gitguardian.example.com).

   If you leave this blank, GitLab uses the default US SaaS endpoint ( https://api.gitguardian.com).

6. In API token, paste the token value from GitGuardian.

7. Optional. Select Test settings.

8. Select Save changes.

GitLab is now ready to reject commits based on GitGuardian policies.

Skip secret detection

{{< history >}}

• Introduced in GitLab 17.0.

{{< /history >}}

You can skip GitGuardian secret detection, if needed. The options to skip secret detection for all commits in a push are identical to the options for native secret detection. Either:

• Add [skip secret push protection] to one of the commit messages.
• Use the secret_push_protection.skip_all push option.

Known issues

• Pushes can be delayed or can time out. With the GitGuardian integration:
  • Pushes are sent to a third-party.
  • GitLab has no control over the connection with GitGuardian or the GitGuardian process.
• Due to a GitGuardian API limitation, the integration ignores files over the size of 1 MB. They are not scanned.
• If a pushed file has a name over 256 characters, the push fails.
• For more information, see GitGuardian API documentation.

Troubleshooting steps below show how to mitigate some of these problems.

Troubleshooting

When working with the GitGuardian integration, you might encounter the following issues.

500 HTTP errors

You might get an HTTP 500 error.

This issue occurs for when requests time out for commits with a lot of changed files.

If this issue happens when you change more than 50 files in a commit:

1. Split your changes into smaller commits.
2. Push the smaller commits one by one.

Error: Filename: ensure this value has at most 256 characters

You might get an HTTP 400 error that states Filename: ensure this value has at most 256 characters.

This issue occurs when some of the changed files you are pushing in that commit have the filename (not the path) longer then 256 characters.

The workaround is to shorten the filename if possible. For example, if the filename cannot be shortened because it was automatically generated by a framework, disable the integration and try to push again. Don't forget to re-enable the integration afterwards if needed.