ContextQMD
Back to Gitlabhq

GitGuardian

doc/user/project/integrations/git_guardian.md

18.11.25.0 KB
Original Source

{{< details >}}

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

{{< /details >}}

{{< history >}}

{{< /history >}}

GitGuardian is a cybersecurity service that detects sensitive data such as API keys and passwords in source code repositories. It scans Git repositories, alerts on policy violations, and helps organizations fix security issues before hackers can exploit them.

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. Select Settings > Integrations.
  3. Select GitGuardian.
  4. In Enable integration, select the Active checkbox.
  5. In API token, paste the token value from GitGuardian.
  6. Optional. Select Test settings.
  7. Select Save changes.

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

Skip secret detection

{{< history >}}

{{< /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.