Secret push protection

DETAILS: Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

• Introduced in GitLab 16.7 as an experiment for GitLab Dedicated customers.
• Changed to Beta and made available on GitLab.com in GitLab 17.1.
• Enabled on self-managed in GitLab 17.2 with flags named pre_receive_secret_detection_beta_release and pre_receive_secret_detection_push_check.
• pre_receive_secret_detection_beta_release feature flag removed in GitLab 17.4.
• Generally available in GitLab 17.5.

FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to disable the feature flag named pre_receive_secret_detection_push_check.

Secret push protection blocks secrets such as keys and API tokens from being pushed to GitLab. The content of each commit is checked for secrets when pushed to GitLab. If any secrets are detected, the push is blocked.

Use pipeline secret detection together with secret push protection to further strengthen your security.

For an overview, see the playlist Get Started with Secret Push Protection.

Regardless of the Git client, GitLab prompts a message when a push is blocked, including details of:

• Commit ID containing the secret.
• Filename and line containing the secret.
• Type of secret.

For example, the following is an extract of the message returned when a push using the Git CLI is blocked. When using other clients, including the GitLab Web IDE, the format of the message is different but the content is the same.

remote: PUSH BLOCKED: Secrets detected in code changes
remote: Secret push protection found the following secrets in commit: 37e54de5e78c31d9e3c3821fd15f7069e3d375b6
remote:
remote: -- test.txt:2 GitLab Personal Access Token
remote:
remote: To push your changes you must remove the identified secrets.

If secret push protection does not detect any secrets in your commits, no message is displayed.

Detected secrets

Secret push protection scans commits for specific patterns. Each pattern matches a specific type of secret. To confirm which secrets are detected by secret push protection, see Detected secrets. Only high-confidence patterns were chosen for secret push protection, to minimize delay when pushing your code and minimize the number of false alerts. You cannot customize the ruleset used by secret push protection.

Enable secret push protection

On GitLab Dedicated and Self-managed instances, secret push protection must be enabled for the entire instance and then you must enable it per project.

On GitLab.com, this setting has been enabled for the entire instance. You must enable it per project.

Allow the use of secret push protection in your GitLab instance

NOTE: Setting this option gives permission for projects in your GitLab instance to turn on secret push protection. To use secret push protection, you must also enable it in each project. For details, see enable secret push protection in a project.

Prerequisites:

• You must be an administrator for your GitLab instance.

1. Sign in to your GitLab instance as an administrator.
2. On the left sidebar, at the bottom, select Admin.
3. Select Settings > Security and compliance.
4. Under Secret detection, select or clear Allow secret push protection.

Enable secret push protection in a project

Prerequisites:

• You must have at least the Maintainer role for the project.

To enable secret push protection in a project:

1. On the left sidebar, select Search or go to and find your project.
2. On the left sidebar, select Secure > Security configuration.
3. Turn on the Secret push protection toggle.

Coverage

Secret push protection checks the content of each commit when it is pushed to GitLab. However, the following conditions apply:

Secret push protection does not block a secret being pushed when either the following apply:

• When pushing commits you specified that secret push protection is to be skipped.
• A secret detection exclusion defines the secret as being out of scope.

Secret push protection does not check a file in a commit when:

• The file is a binary file.
• The file is larger than 1 MiB.
• The diff patch for the file is larger than 1 MiB (when using diff scanning).
• The file was renamed, deleted, or moved without changes to the content.
• The content of the file is identical to the content of another file in the source code.
• The file is contained in the initial push that created the repository.

Diff scanning

• Introduced in GitLab 17.5 with a project-level flag named spp_scan_diffs.

Secret Push Protection scans all contents of modified files by default. This can cause a push to be blocked unexpectedly when a file containing a secret is scanned. You can enable the spp_scan_diffs feature flag for your project, which modifies Secret Push Protection to only scan newly committed changes (or diffs), and not the rest of the file.

When spp_scan_diffs is enabled, Secret Push Protection scans the diffs for CLI-based pushes via HTTP/SSH. Changes committed via the WebIDE still result in the entire file being scanned due to a technical limitation. Issue 491282 addresses the limitation so only the diffs are scanned for WebIDE changes.

Resolve a blocked push

When secret push protection blocks a push, you can either:

• Remove the secret
• Skip secret push protection

Remove the secret

Remove a blocked secret to allow the commit to be pushed to GitLab. The method of removing the secret depends on how recently it was committed. The instructions below use the Git CLI client, but you can achieve the same result by using another Git client.

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. Optional. Watch a short demo of removing secrets from your commits.
2. Identify the commit SHA from the push error message. If there are multiple, find the earliest using git log.
3. Create a copy branch to work from with git switch --create copy-branch so you can reset to the original branch if the rebase encounters issues.
4. Use git rebase -i <commit-sha>~1 to start an interactive rebase.
5. Mark the offending commits for editing by changing the pick command to edit in the editor.
6. Remove the secrets from the files.
7. Stage the changes with git add <file-name>.
8. Commit the changed files with git commit --amend.
9. Continue the rebase with git rebase --continue until all secrets are removed.
10. Push your changes from the copy branch to your original remote branch with git push --force --set-upstream origin copy-branch:<original-branch>.
11. When you are satisfied with the changes, consider the following optional cleanup steps.
    1. Optional. Delete the original branch with git branch --delete --force <original-branch>.
    2. Optional. Replace the original branch by renaming the copy branch with git branch --move copy-branch <original-branch>.

Skip secret push protection

In some cases, it may be necessary to skip secret push protection. For example, a developer may need to commit a placeholder secret for testing, or a user may want to skip secret push protection due to a Git operation timeout.

Audit events are logged when secret push protection is skipped. Audit event details include:

• Skip method used.
• GitLab account name.
• Date and time at which secret push protection was skipped.
• Name of project that the secret was pushed to.

If pipeline secret detection is enabled, the content of all commits are scanned after they are pushed to the repository.

To skip secret push protection for all commits in a push, either:

• If you're using the Git CLI client, instruct Git to skip secret push protection.
• If you're using any other client, add [skip secret push protection] to one of the commit messages.

Skip when using the Git CLI client

To skip secret push protection when using the Git CLI client:

• Use the push option.

  For example, you have several commits that are blocked from being pushed because one of them contains a secret. To skip secret push protection, you append the push option to the Git command.

  git push -o secret_push_protection.skip_all

Skip when using any Git client

To skip secret push protection when using any Git client:

• Add [skip secret push protection] to one of the commit messages, on either an existing line or a new line, then push the commits.

  For example, you are using the GitLab Web IDE and have several commits that are blocked from being pushed because one of them contains a secret. To skip secret push protection, edit the latest commit message and add [skip secret push protection], then push the commits.

Troubleshooting

When working with secret push protection, you may encounter the following situations.

Push blocked unexpectedly

Secret Push Protection scans all contents of modified files. This can cause a push to be unexpectedly blocked if a modified file contains a secret, even if the secret is not part of the diff.

Enable the spp_scan_diffs feature flag to ensure that only newly committed changes are scanned. To push a WebIDE change to a file that contains a secret, you need to skip secret push protection.

File was not scanned

Some files are excluded from scanning. For a list of exclusions, see coverage.