In GitLab, how does secret push protection differ from pipeline secret detection, and why would a team run both?
answer
- before the push lands, or after
- pre-receive check versus CI job
- high-confidence patterns, diffs only
- skips, bypasses and history
basics
~20 sSecret push protection (Ultimate) checks a push's changes before GitLab accepts them and rejects a push containing a secret. Pipeline secret detection (every tier) scans commits in a CI job after they land, catching what push protection missed.
solid answer
~50 sSecret push protection runs in GitLab's pre-receive hook. Since GitLab 17.11 it scans only the diffs pushed over HTTP(S) or SSH, using only high-confidence patterns, and it rejects the push with the commit, file, line and secret type. It is deliberately narrow: it skips binary files, files or diffs over 1 MiB, the initial push that creates a repository, and pushes changing more than 3,150 paths or 350,000 lines. A developer can bypass it with `git push -o secret_push_protection.skip_all` or `[skip secret push protection]` in a commit message, and the bypass is logged as an audit event. Pipeline secret detection is the `secret_detection` job from `Jobs/Secret-Detection.gitlab-ci.yml`. It runs after the push, uses the full default ruleset, and with a one-off historic scan covers existing history. Push protection stops most leaks at the door; the pipeline scan is the net under it.
go deeper
Remember the timing: push protection rejects the push before it lands, while pipeline secret detection reports after the commit is already in GitLab.
Explain push protection's limits (diffs only, high-confidence patterns, size and path thresholds, bypass options) and what the secret_detection job and a historic scan cover.
Plan the rollout: instance allow setting, project or group enablement, a one-off historic scan, audit review of skips, and what happens when a secret does get through.
Balance developer friction against coverage. Push protection is tuned to be fast and quiet, so the layered design with a pipeline net is a deliberate trade-off, not redundancy.
## Two checks at two moments GitLab offers two ways to catch credentials committed to a repository. They differ in **when** they run, and that difference decides everything else. | | Secret push protection | Pipeline secret detection | |---|---|---| | When | During the push, in the pre-receive hook, before GitLab accepts it | In a CI/CD job, after the commits are in the repository | | Tier | Ultimate | Free, Premium, Ultimate (merge request and vulnerability report views on Ultimate) | | What it reads | The diffs of the pushed commits | The commits the pipeline covers, or full history in a historic scan | | Rules | High-confidence patterns only | The full default ruleset, customizable on Ultimate | | Outcome | The push is rejected | A finding in the job's report | | Bypass | A push option or a commit-message marker, audited | Not applicable: it reports rather than blocks | **Secret push protection** prevents the leak: the secret never reaches the server. **Pipeline secret detection** detects a leak that has already happened. Once a secret is in a pushed commit, assume it is exposed; finding it later does not undo that. ## Turning each one on - Secret push protection on **GitLab Self-Managed** and **GitLab Dedicated** needs two steps. An administrator first turns on **Allow secret push protection** in the instance's security and compliance settings. Then each project turns on the **Secret push protection** toggle on its **Security configuration** page, which needs the Security Manager, Maintainer or Owner role. A group can switch it on for all of its projects through the API. - On **GitLab.com**, only the project toggle is needed. - Pipeline secret detection is enabled by including `Jobs/Secret-Detection.gitlab-ci.yml`, by a configured merge request from the **Security configuration** page, or, on Ultimate, by a scan execution policy. ## What push protection does not see Push protection trades coverage for speed, so that pushes stay fast and false alarms stay rare. It does **not** check a file when: - the file is binary; - the file or diff patch is larger than 1 MiB; - the file was renamed, deleted or moved without content changes; - the file's content is identical to another file in the source code; - it is part of the initial push that created the repository. It also skips the whole push when it changes more than 3,150 paths or 350,000 lines. Since GitLab 17.11 it scans only diffs, so a secret already sitting in a file is invisible unless the push changes those lines. Because only high-confidence patterns are used, some token types are not detected at all; personal access tokens with a custom prefix are one documented example. ## Skipping it, on the record Developers sometimes need to push a placeholder value, or hit a timeout. GitLab allows two ways to skip the check for every commit in a push: 1. From the Git command line: `git push -o secret_push_protection.skip_all`. 2. From any client, including the Web IDE: add `[skip secret push protection]` to one of the commit messages. Each skip produces an **audit event** recording the method, the account, the time, the project, the target branch and the commits. Since GitLab 19.4 a blocked push is also recorded as an audit event. If pipeline secret detection is enabled, the skipped commits are still scanned after the push. ## What pipeline secret detection covers The `secret_detection` job does not rescan the whole repository every time: - On the default branch it scans the commits since the previous push, when a valid earlier commit is available. - On a feature branch, recent analyzer versions scan every commit since the branch diverged from the default branch. - In a merge request pipeline it scans all commits on the branch. - By default the job covers the repository's current state and new commits. Secrets that exist only in earlier commits are found by a **historic scan**, a one-off run with `SECRET_DETECTION_HISTORIC_SCAN` set to `true`, which GitLab recommends right after enabling the analyzer. ## Why run both 1. Push protection stops the common case before any exposure, at almost no cost to developers. 2. Pipeline detection catches what push protection skips: large pushes, big files, bypassed pushes, lower-confidence patterns and pre-existing history. 3. On Ultimate, pipeline findings flow into the merge request report and the vulnerability report, where they can be triaged and enforced by policy. 4. Neither replaces rotating a credential that was actually pushed.
- On GitLab Self-Managed, a Maintainer cannot find a way to turn on secret push protection for a project. What is missing?An administrator must first allow it for the whole instance with the Allow secret push protection setting under the instance's secret detection settings. Only then does the project's Secret push protection toggle on the Security configuration page work, for the Security Manager, Maintainer or Owner role.
- In GitLab, a developer bypassed secret push protection with a commit-message marker. What record and what second check remain?The skip is logged as an audit event with the skip method, the account, the time, the project, the target branch and the commits that skipped the check. If pipeline secret detection is enabled, the pushed commits are still scanned in the secret_detection job after the push.
- GitLab secret push protection scans the whole repository on every push.
- Secret push protection on GitLab makes pipeline secret detection redundant.
- A secret blocked by push protection can be bypassed silently, with no record.
- Pipeline secret detection blocks the push before the secret reaches GitLab.
- Pipeline secret detection finds secrets that exist only in old commits without a historic scan.
Assumes GitLab 19.4; secret push protection has been generally available since 17.5, scans only pushed diffs since 17.11, and audits blocked pushes since 19.4.