Skip to main content
Video tutorial · 1:00

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 valueWhat it doesEffect on the merge gate
OffoffThe merge request is not scannedNone
ReportreportThe merge request is scanned; findings are shown on it, marked (report only)None
EnforceblockThe merge request is scanned; findings hold itWaiting 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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Mode (row Secret scan)See ModesOffOff, Report, EnforcePolicyPolicy manager, company admin, platform admincontrols.secret_scan.mode (off, report, block)
Files the VCS sends no diff forWhat 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 reviewedWarn, do not holdwarn, blockCompany; policy override (editor: Warn / Hold the change)Company: company admin. Policy: policy manager, company adminscanning.secrets.unscanned_files; controls.secret_scan.overrides.unscanned_files
"gitleaks:allow" commentsWhether 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 saysHonour, and reportreport, ignoreCompany; policy override (editor: Honour, and report / Ignore them)Samescanning.secrets.inline_allow; controls.secret_scan.overrides.inline_allow
When the scan cannot finishFail, 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 handmanual, retryCompany; policy overrideSamescanning.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 itLow (every finding)Low (every finding), Medium, High, CriticalCompany; policy overrideSamescanning.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 descriptionOnOn, off (editor: Scan them / Do not scan)Company; policy overrideSamescanning.secrets.scan_texts; controls.secret_scan.overrides.scan_texts
Enable custom detection rulesAdds 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 reportedOffOn, offCompany; policy override through the API onlySamescanning.secrets.custom_rules_enabled; controls.secret_scan.overrides.custom_rules_enabled
Allowed pathsFiles that are not scannedEmptyOne 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 foldersCompany; policy override through the API onlySamescanning.secrets.allowed_paths; controls.secret_scan.overrides.allowed_paths
Allowed rulesRules that are not run. The tab lists every rule, Custom rules (mp-) and the built-in ones, with search and Select allNoneRule IDs (GET /api/v1/scanner/rules lists them)Company; policy override through the API onlySamescanning.secrets.allowed_rules; controls.secret_scan.overrides.allowed_rules
Decoding depthHow many times encoded text is decoded to find secrets hidden in it. 0 turns decoding off50 to 10CompanyCompany adminscanning.secrets.decode_depth
Max findings per scanHow many findings are stored and listed; the count includes all of them500 to 1000 (0: the default)CompanyCompany adminscanning.secrets.max_findings
External call timeout (seconds)How long each call to the VCS during the scan may take. Increase it for large merge requests300 to 600 (0: the default)CompanyCompany adminscanning.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 scanning object 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:

WayScopeWho
gitleaks:allow on the line, for example token = "abc123" # gitleaks:allowThat 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_inlineThe change's author
Allowed pathsEvery file matching a patternCompany admin (or a policy through the API)
Allowed rulesEvery finding of a ruleCompany 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}/rescan with {"scan": "secret"}. Recorded as secret_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​

StatusMessage
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​

ActionWhen
secrets_detectedThe scan found possible secrets, and they differ from the previous scan's
secrets_allowed_inlineFindings were allowed with gitleaks:allow, and they differ from the previous scan's
secret_rescanSomeone started a re-scan
job_failedThe scan job failed after its retries
update_companyThe company's scan settings were changed
policy_updatedA policy's mode or overrides were changed

See Audit log.

API​

  • Policy: controls.secret_scan with mode and overrides (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_scan with status (pending, completed, failed), head_sha, total_count (every finding), stored_count (those kept in findings), findings (rule_id, description, file, start_line, severity), suppressed, unscanned, truncated, files_scanned, error; and the result in decision.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 →

Catch a Leaked Secret Before It MergesYouTube ↗