Skip to content

Pre-receive secret detection

DETAILS: Tier: Ultimate Offering: GitLab Dedicated Status: Experiment

NOTE: This feature is an Experiment, available only on GitLab Dedicated, and is subject to the GitLab Testing Agreement.

Pre-receive secret detection scans the contents of committed files when they are pushed to a remote repository to prevent the accidental exposure of secrets like keys or API tokens to your repositories. If any secrets are detected, the push is blocked, ensuring that the secrets do not reach your instance.

Pre-receive secret detection is an Experiment, and only available on GitLab Dedicated. To use secret detection in your instance, use pipeline secret detection instead.

Enable pre-receive secret detection

Prerequisites:

  • You must be an administrator for your GitLab Dedicated instance.
  1. Sign in to your GitLab Dedicated instance as an administrator.
  2. On the left sidebar, at the bottom, select Admin Area.
  3. Select Settings > Security and Compliance.
  4. Expand Secret Detection.
  5. Select the Enable pre-receive secret detection checkbox.

Limitations

  • This feature only scans non-binary blobs under 1 MiB in size. Binary blobs and blobs larger than 1 MiB are not scanned.
  • The scan does not analyze the content of a commit if it is identical to the content of another file already present in the source code.
  • The scan skips analyzing files that are renamed, deleted, or moved, unless their content is modified in the same commit.
  • The feature does not analyze files that are introduced during a repository creation.

Resolve a blocked push

If the blocked secret was added with the most recent commit on your branch:

  1. Remove the secrets from the files.
  2. Stage the changes with git add <file-name>.
  3. Modify the most recent commit to include the changed files with git commit --amend.
  4. Push your changes with git push.

If the blocked secret appears earlier in your Git history:

  1. Identify the commit SHA from the push error message. If there are multiple, find the earliest using git log.
  2. Use git rebase -i <commit-sha>~1 to start an interactive rebase.
  3. Mark the offending commits for editing by changing the pick command to edit in the editor.
  4. Remove the secrets from the files.
  5. Stage the changes with git add <file-name>.
  6. Commit the changed files with git commit --amend.
  7. Continue the rebase with git rebase --continue until all secrets are removed.
  8. Push your changes with git push.

Skip secret detection

In some cases, it may be necessary to skip pre-receive secret detection. For example, a developer may need to commit a placeholder secret for testing, or a user may want to bypass secret detection due to a Git operation timeout. To skip secret detection for all commits in a push, add [skip secret detection] to one of the commit messages. For example:

# These commits are in the same push. Both will not be scanned.
Add real secret by accident
Add placeholder token to test file [skip secret detection]

NOTE: Pipeline secret detection still scans the bypassed secrets when using [skip secret detection] in one of your commit messages.