Secret scan
The Secret scan control looks for credentials, keys and tokens that a merge request adds: in the lines it adds, in the names of the files it adds or changes and, by default, in its commit messages, title and description. In Enforce mode a change with a possible secret cannot merge until the secret is removed or the finding is allowed.
Whether a merge request is scanned, and whether findings hold it, is set per change policy (policy editor, Checks tab, row Secret scan). How the scan behaves is a company setting (the company's Scanning tab → Secrets), which a policy can override.
Modes
| Mode (label in the UI) | API value | What it does | Effect on the merge gate |
|---|---|---|---|
| Off | off | The merge request is not scanned | None |
| Report | report | The merge request is scanned; findings are shown on it, marked (report only) | None |
| Enforce | block | The merge request is scanned; findings hold it | Waiting while the scan runs; Blocked on a finding, a failed scan, or (with Hold the change) files that could not be scanned |
A new policy starts with Off. By default every finding counts, whatever its severity; Lowest severity that holds a merge can leave lower-severity findings listed only (see Settings). A finding accepted by an active exception does not count either.
What is scanned
- Added lines. Only lines the merge request adds are reported. A secret already in the file, shown around a change, is not this change's finding.
- File names. Some rules look at a file's name alone (key stores, private key files), so a binary key store is found even though it has no diff.
- Commit messages, title and description, every line, when Scan commit messages and the merge request description is on.
- Encoded text. Text encoded in base64, hex or percent-encoding is decoded and scanned, up to the Decoding depth.
- Not scanned: deleted files, and files matching Allowed paths.
Files the VCS sends without a diff are handled this way: a file with a binary extension (images, archives, fonts, key stores and similar) is checked by name and counts as scanned; any other such file (very large, cut off) is listed as not scanned, and so is the case where the VCS listed only part of the changed files. What that does to the result is the Files the VCS sends no diff for setting.
The secret itself is never stored or shown: a finding records the rule, the file, the line and the severity.
Settings
The company's settings are on the company's Scanning tab → Secrets; company admins change them there (PUT /api/v1/companies/{id} with scanning.secrets). A policy can take its own value for some of them in the policy editor (section shown under the Secret scan row when it is not Off; each list starts on Company setting (…), showing the company's current choice). Others can be overridden through the API only.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Mode (row Secret scan) | See Modes | Off | Off, Report, Enforce | Policy | Policy manager, company admin, platform admin | controls.secret_scan.mode (off, report, block) |
| Files the VCS sends no diff for | What a file that could not be scanned does. Warn, do not hold: listed as not scanned; the change can still pass. Hold the change: the scan fails (holding the merge in Enforce) until the change is split or reviewed | Warn, do not hold | warn, block | Company; policy override (editor: Warn / Hold the change) | Company: company admin. Policy: policy manager, company admin | scanning.secrets.unscanned_files; controls.secret_scan.overrides.unscanned_files |
| "gitleaks:allow" comments | Whether an author may exempt a line (see Allowing a finding). Honour, and report: the finding does not count but is listed and audited. Ignore them: findings count whatever the line says | Honour, and report | report, ignore | Company; policy override (editor: Honour, and report / Ignore them) | Same | scanning.secrets.inline_allow; controls.secret_scan.overrides.inline_allow |
| When the scan cannot finish | Fail, rescan by hand: an unreachable VCS or a failed read fails the scan (never "clean"); someone re-scans. Fail, retry automatically: the scan fails the same way and is retried after a pause until it completes. (The CI configuration check follows When a scan cannot see everything instead, see Scanning) | Fail, rescan by hand | manual, retry | Company; policy override | Same | scanning.secrets.on_error; controls.secret_scan.overrides.on_error |
| Lowest severity that holds a merge (policy editor: Lowest severity that holds the merge) | Findings below it are listed on the merge request but do not hold it | Low (every finding) | Low (every finding), Medium, High, Critical | Company; policy override | Same | scanning.secrets.min_severity; controls.secret_scan.overrides.min_severity (low, medium, high, critical) |
| Scan commit messages and the merge request description (policy editor: Commit messages and description) | Also scan the commit messages and the merge request's title and description | On | On, off (editor: Scan them / Do not scan) | Company; policy override | Same | scanning.secrets.scan_texts; controls.secret_scan.overrides.scan_texts |
| Enable custom detection rules | Adds Merge Pilot's own rules (IDs starting mp-): database connection strings with a password, password and secret assignments, URLs with credentials, Bearer and Authorization tokens, Kubernetes bootstrap tokens, GitLab CI and runner tokens, Jira API tokens. Placeholders such as ${VAR}, <password> or changeme are not reported | Off | On, off | Company; policy override through the API only | Same | scanning.secrets.custom_rules_enabled; controls.secret_scan.overrides.custom_rules_enabled |
| Allowed paths | Files that are not scanned | Empty | One pattern per line. A pattern without / matches a file or folder name anywhere (*.test.go, testdata); one with / is read from the repository root (docs/**, /scripts); ** spans folders | Company; policy override through the API only | Same | scanning.secrets.allowed_paths; controls.secret_scan.overrides.allowed_paths |
| Allowed rules | Rules that are not run. The tab lists every rule, Custom rules (mp-) and the built-in ones, with search and Select all | None | Rule IDs (GET /api/v1/scanner/rules lists them) | Company; policy override through the API only | Same | scanning.secrets.allowed_rules; controls.secret_scan.overrides.allowed_rules |
| Decoding depth | How many times encoded text is decoded to find secrets hidden in it. 0 turns decoding off | 5 | 0 to 10 | Company | Company admin | scanning.secrets.decode_depth |
| Max findings per scan | How many findings are stored and listed; the count includes all of them | 50 | 0 to 1000 (0: the default) | Company | Company admin | scanning.secrets.max_findings |
| External call timeout (seconds) | How long each call to the VCS during the scan may take. Increase it for large merge requests | 30 | 0 to 600 (0: the default) | Company | Company admin | scanning.secrets.external_call_timeout |
Notes:
- A policy override list replaces the company's list, even when empty; leaving it out (
null) keeps the company's. - The company's
scanningobject is saved as a whole: fields left out take their defaults. - Changes to the company's settings, and to a policy's overrides, take effect at the next scan (a new commit or a re-scan). Files the VCS sends no diff for and Lowest severity that holds a merge are applied when the merge request is next evaluated, without a new scan.
Allowing a finding
There are three ways to keep a known false positive from holding a change:
| Way | Scope | Who |
|---|---|---|
gitleaks:allow on the line, for example token = "abc123" # gitleaks:allow | That line. Honoured only while "gitleaks:allow" comments is Honour, and report; the finding is then listed under Allowed by the author and written to the audit log as secrets_allowed_inline | The change's author |
| Allowed paths | Every file matching a pattern | Company admin (or a policy through the API) |
| Allowed rules | Every finding of a rule | Company admin (or a policy through the API) |
When it runs
- Once per commit. When the merge request is processed and its latest commit has not been scanned yet, the scan is queued. New commits start a new scan, and the card shows Scan in progress until it finishes.
- Re-scan. The Re-scan button on an open merge request's Secret scan card scans the latest commit again (a merged or closed merge request is not scanned again). Anyone in the company except auditors can use it. API:
POST /api/v1/merge-requests/{id}/rescanwith{"scan": "secret"}. Recorded assecret_rescan. - After a failure, with Fail, retry automatically: the scan is queued again after a pause (10 minutes by default), the next time the merge request is processed (for example by the periodic re-check). With Fail, rescan by hand, it waits for a re-scan.
- A VCS rate limit is not a failure: the job waits for the limit to reset (see Jobs).
- Watched repositories are scanned only while the company scans watched merge requests (company Repositories tab, Watching repositories: Scan watched merge requests for secrets, vulnerable dependencies and licenses), and imported past merge requests only with Also scan imported merge requests for secrets and vulnerable dependencies. Otherwise the control is skipped ("Not scanned: scans are off for watched repositories."), and a re-scan of a watched merge request is refused (scans are off for watched repositories (Company → Repositories), HTTP
409).
When the scan finishes, the merge request is evaluated again.
What the control says
| Status | Message |
|---|---|
| Pending | "Scanning the change for secrets." |
| Passed | "No secrets found.", or "No secrets that hold the merge." with "N finding(s) below … severity are listed only." and "N finding(s) accepted by an exception." (with "N finding(s) marked gitleaks:allow by the author." and, under Warn, do not hold, "Warning: N changed file(s) could not be scanned …") |
| Failed | "N possible secret(s) found in the change." When more findings hold the merge than the scan keeps (Max findings per scan), it adds "N of them are beyond the findings kept per scan: raise the secret scan's findings kept (Company → Scanning) and rescan to see and accept them." |
| Failed | "No secrets found, but N changed file(s) could not be scanned …" (under Hold the change) |
| Failed | "The secret scan failed: …" |
What the merge request shows
On the merge request page, the Secret scan card shows Scan in progress, No secrets detected (N files scanned) or N potential secret(s) detected, with each finding's severity, file:line, description and rule ID. It also lists what could not be scanned (Not everything could be scanned), the lines the author allowed, and Scan failed: … when the scan failed.
In the VCS, Merge Pilot keeps one comment, Merge Pilot: Secret Scan, up to date on the merge request once there is something to say: the findings grouped by severity (file, line, rule), the lines allowed by the author and the files not scanned. The secret is never in the comment. No comment is written in a watched repository.
When the findings change, the notification Secrets found in a merge request goes to the company's notification routes that receive it (not for imported past merge requests).
GitLab and GitHub
The scan is the same on both. GitHub pages and comments say pull request.
Audit
| Action | When |
|---|---|
secrets_detected | The scan found possible secrets, and they differ from the previous scan's |
secrets_allowed_inline | Findings were allowed with gitleaks:allow, and they differ from the previous scan's |
secret_rescan | Someone started a re-scan |
job_failed | The scan job failed after its retries |
update_company | The company's scan settings were changed |
policy_updated | A policy's mode or overrides were changed |
See Audit log.
API
- Policy:
controls.secret_scanwithmodeandoverrides(unscanned_files,inline_allow,on_error,min_severity,scan_texts,custom_rules_enabled,allowed_paths,allowed_rules). - Company:
scanning.secrets(custom_rules_enabled,allowed_paths,allowed_rules,max_findings,external_call_timeout,unscanned_files,inline_allow,scan_texts,decode_depth,on_error,min_severity). - Merge request (
GET /api/v1/merge-requests/{id}):secret_scanwithstatus(pending,completed,failed),head_sha,total_count(every finding),stored_count(those kept infindings),findings(rule_id,description,file,start_line,severity),suppressed,unscanned,truncated,files_scanned,error; and the result indecision.controls(control: "secret_scan"). - Rules:
GET /api/v1/scanner/rules(rule_id,description,is_custom).
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →