Secret Push Protection is now generally available for all GitLab Ultimate and GitLab Dedicated customers. Secret Push Protection blocks secrets such as keys and API tokens from being pushed to GitLab. The content of each commit is checked for high-confidence secrets when pushed to GitLab. If any high-confidence secrets are detected, the push is blocked. By protecting secrets from leaking in the first place, your team can greatly reduce risk and reduce time spent on rotating secrets.
The risk of leaked secrets
Secrets, such as tokens and API keys, are frequently used by applications to authenticate and provide access to sensitive data. Developers sometimes inadvertently hardcode these secrets, and then push that code into source management systems, like GitLab. Hardcoded secrets stored in plain text are a low-effort, high-value target for malicious actors, as numerous recent high-profile breaches have demonstrated. Secrets do not require any special skills to exploit and many secrets do not automatically expire. Therefore, once a malicious actor has access to a secret, they can continue using it indefinitely to cause data breaches, service disruptions, IP theft, source code theft, and software supply chain compromises. Both Verizon’s annual Data Breach Investigations Report and IBM’s annual Cost of a Data Breach report have repeatedly reported that compromised credentials, which include secrets, are one of the most frequent and expensive source of breaches.
IBM’s research also indicates that taking a DevSecOps, or shift-left, approach is the most effective way to reduce the average cost of a data breach. Until now, GitLab’s primary secret detection method has been Pipeline Secret Detection, which scans committed files after they have been pushed to GitLab and identifies secrets that are already leaked. Once a secret has leaked, it should be considered compromised and must be rotated according to the steps outlined by the secret issuer. Remediating detected secrets requires security teams and developers to work closely together to follow the steps outlined by a secret issuer to rotate the leaked secret. It can be a tedious, confusing, and risky process. Utilizing GitLab’s Secret Push Protection feature, you can shift secret detection further left, protect your secrets from leaking in the first place, and reduce the amount of time and energy required to remediate leaks.
How Secret Push Protection works
Once Secret Push Protection is enabled on a project, developers are blocked from pushing code to projects that contain any high-confidence secrets. This ensures a performant experience when pushing your code and also results in a lower number of false alerts. Note: Here is the list of high-confidence patterns Secret Push Protection supports.
While we are checking the contents of each commit, we've excluded a number of factors in order to optimize the performance of this workflow. Because of this, we recommend using Secret Push Protection in a layered approach alongside Pipeline Secret Detection. Using both features in tandem maximizes coverage to identify more leaked secrets across the software development lifecycle.
Get started with Secret Push Protection
We've put a video playlist together to help you get started on using this feature:
Enable Secret Push Protection
On GitLab Dedicated and Self-managed, you must allow the use of Secret Push Protection in your instance and then enable it per project. On GitLab.com, you only need to enable it per project.
You must have at least the Maintainer role to enable push protection for the project.
- On the left sidebar, select Search or Go to and find your project.
- On the left sidebar, select Secure > Security configuration.
- Turn on the Secret Push Protection toggle.
Skip push protection
In some instances, when a push is blocked, you might find it necessary to skip Secret Push Protection. For example, a developer may need to commit a placeholder secret for testing. You can skip Secret Push Protection via a Git option or commit message, meeting developers in whichever Git client they are using.
Add exclusions
We released exclusions, giving you flexibility to exclude certain paths, rules from the default ruleset, or raw values from being scanned, detected, and blocked by push protection. From the Security Configuration page, Maintainers and project Owners can manage push protection exclusion lists within the UI on a per-project basis.
Audit events
Disabling Secret Push Protection, or even skipping it altogether, can prove to be costly if not done for the appropriate reasons. We've introduced audit events to help administrators and security teams understand where and how this feature is being used, and to assist in any secrets-related investigations.
We currently log audit events when Secret Push Protection is:
- enabled/disabled at an instance level
- enabled/disabled at project level
- skipped via a push option
- skipped via a commit message
And when an exclusion is:
- created
- updated
- deleted
These audit events can be used in conjunction with audit event streaming to manage audit logs in third-party systems (like SIEMs), enabling customers to capture trends such as: how many times push protection is being skipped; which projects frequently bypass push protection; and which secrets are commonly skipped and may need to be excluded moving forward.
Dogfooding Secret Push Protection
We dogfood everything here at GitLab. We've collaborated with various teams across the organization to enable this feature across key projects, including our primary GitLab codebase. This process has enabled us to identify and address improvements early in the development process, and it has increased our confidence in the stability, performance, and customer workflows for the release of this feature.
What's next
You can help us improve this feature by commenting on this Secret Push Protection feedback issue. We’ll incorporate your feedback and make additional improvements as we continue to add new capabilities to the feature.
Learn more about the Secret Push Protection.