Catch secrets before commit with gitleaks and pre-commit

Block credentials at the git hook, scan history for what already leaked, and wire the same check into CI.

A secret that reaches a commit has to be rotated, because a clone, a fork, a CI cache or a mirror may already hold it, and rewriting history removes it from none of those. The cheap outcome is the one above: the hook ran on the staged diff, the commit was refused, and the only cleanup is deleting a line. gitleaks is the scanner in all three places this post covers, and since v8.19 its commands are git, dir and stdin; detect and protect still run but are deprecated, and most copied snippets use them.

The hook: pinned, and easy to bypass by design

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1                 # a tag; pre-commit autoupdate bumps it in a reviewable diff
    hooks:
      - id: gitleaks             # upstream entry: gitleaks git --pre-commit --redact --staged --verbose
 

The upstream hook definition already passes --pre-commit --staged --redact, so the id alone is the whole configuration, and adding args duplicates or contradicts it. pre-commit install writes .git/hooks/pre-commit once per clone, which is the hook's limit: a developer who never ran it, a machine set up last year, or SKIP=gitleaks git commit (a documented, legitimate bypass for a known false positive) all skip it. The hook is for fast feedback at the keyboard. Enforcement lives in the next section, and treating the hook as enforcement is the mistake that makes teams surprised when CI finds a key. One detail for anyone testing the hook: the access key id from the AWS documentation, AKIAIOSFODNN7EXAMPLE, is allowlisted by the default rules and produces no finding, so a test with it proves nothing; use a made-up id with the same shape.

CI is the gate, with the same version and config

secret_scan:
  stage: test
  image:
    name: ghcr.io/gitleaks/gitleaks:v8.30.1
    entrypoint: [""]
  variables:
    GIT_DEPTH: 0                              # the git command needs history, not a shallow clone
  script:
    - gitleaks git --redact --exit-code 1 --report-format sarif --report-path gitleaks.sarif
        --log-opts="$CI_MERGE_REQUEST_DIFF_BASE_SHA..HEAD" .
  artifacts:
    when: always
    paths: [gitleaks.sarif]
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

--log-opts narrows the scan to the commits the merge request adds, which keeps the job fast and keeps a decade of history from failing every pipeline. The image tag and the hook's rev should match, and a .gitleaks.toml in the repository root is picked up by both automatically, so a rule tuned for the hook behaves the same in CI. Required on protected branches, this job is what makes --no-verify pointless. GitLab's own Secret Detection template is the alternative for teams that want the findings in the security dashboard rather than as an artifact; it runs a different engine, so keep one or the other as the gate.

History: scan once, baseline, then only new findings

Twenty-three findings on a first run is normal, and they make a triage list rather than twenty-three incidents. Fixtures and test keys get a gitleaks:allow comment on the line, or a fingerprint in .gitleaksignore, each with a reason in the commit that adds it. The two waivers have different scopes, and the run showed the difference: a fingerprint taken from a git scan carries the commit hash (55cc5b06…:config/prod.env:aws-access-token:4) and silences that finding in history scans, but a gitleaks dir scan of the working tree produces the same finding with a path-only fingerprint and reports it again; the gitleaks:allow comment silences both, and --ignore-gitleaks-allow on the CI job brings it back on demand. The real keys are assumed compromised and rotated in the system that issued them (IAM, the Git host, Vault), and the ticket for each records the date the key first appeared, which the report gives you. History rewriting is a separate decision for repositories that must be published; it shrinks the exposure surface and does not undo it.

Recovering from a false positive or a lost key, in order

Scanning finds secrets that should not be in Git; it does not decide where they should be. Values that belong next to the code go in encrypted with SOPS and age, and the ones CI needs at runtime come from the pipeline's secret store or an OIDC exchange, so there is nothing for the scanner to find.

Related posts

Quick reference