Secret push protection

Tier: Ultimate Offering: GitLab.com, GitLab Dedicated Status: Beta
History

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.

Secret push protection is available on GitLab.com and GitLab Dedicated. To scan for secrets in your GitLab self-managed instance, use pipeline secret detection instead. Pipeline secret detection can be used together with secret push protection to further secure your GitLab.com or Dedicated instance.

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.

Enable secret push protection

On GitLab Dedicated and GitLab.com, secret push protection must be enabled at the instance level and then 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 Area.
  3. Select Settings > Security and Compliance.
  4. Expand Secret Detection.
  5. Select the Allow secret push protection checkbox.

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 exclusions apply.

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

Resolve a blocked push

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

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. 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 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:

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_detection.skip_all

Skip when using any Git client

To skip secret push protection when using any Git client:

  • Add [skip secret detection] 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 detection], then push the commits.