skip to content

~/docs/ci

CI integration

A sweep finds what already leaked. This page stops the next one: a hook before the commit, a gate on the pull request.

The two layers

  • Pre-commit hook. Runs on the developer machine. The key never enters history, so there is nothing to purge.
  • CI gate. Runs on every pull request. Catches what skipped the hook, and blocks the merge.

Both layers below use gitleaks, the open source scanner, because a prevention layer should not depend on any vendor, including us. Leaksweep is what you run when the gate trips, or on the history that predates the gate. On Dev and Team, every sweep generates these files tuned to that repo, with an allowlist seeded from the noise it dismissed.

GitHub Actions

.github/workflows/secret-scan.yml
name: secret-scan
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fetch-depth: 0 gives the scanner full history. Organization accounts also need a free GITLEAKS_LICENSE secret; personal accounts do not.

Then make it a gate: in the repo settings, under Branches, add a branch protection rule for main and require the gitleaks status check to pass before merging.

GitLab CI

.gitlab-ci.yml
secret_scan:
  stage: test
  image:
    name: zricethezav/gitleaks:latest
    entrypoint: [""]
  variables:
    GIT_DEPTH: "0"
  script:
    - gitleaks git --redact --verbose .

--redact keeps found values out of the job log. A CI log is one more place a secret can leak.

Pre-commit hook

.pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks
install once per clone
pip install pre-commit
pre-commit install

No Python on the machine? A plain git hook works too:

.git/hooks/pre-commit
#!/bin/sh
gitleaks git --pre-commit --staged --redact --verbose

chmod +x .git/hooks/pre-commit. '--pre-commit --staged' scans only what is about to be committed, so it runs in well under a second.

Allowlist the confirmed noise

A gate that cries wolf gets disabled. When a Leaksweep finding is confirmed noise (a docs example, a test fixture), allowlist its path so CI stays quiet about it and loud about everything else.

.gitleaks.toml
title = "repo config"

[extend]
useDefault = true

[allowlist]
description = "paths confirmed as placeholders or fixtures"
paths = [
  '''^docs/examples/''',
  '''^test/fixtures/fake_credentials\.json$''',
]

Keep env files out of git

.gitignore
.env
.env.*
!.env.example
*.pem
*.key

If one already slipped in, ignoring it is not enough. Untrack it, then rotate everything it held:

untrack a committed env file
git rm --cached .env
git commit -m "stop tracking .env"

Turn on host push protection

GitHub blocks pushes that contain known credential formats when push protection is on: repo Settings, Code security, Secret scanning, Push protection. It is free for public repos. GitLab has an equivalent under Secure, Security configuration, Secret push protection. Turn it on. It is one more layer and it costs nothing.

When the gate trips

  1. Treat the value as leaked. If the branch was pushed, it left the machine.
  2. Rotate at the issuer. This is always first.
  3. Run a sweep on the branch for the exact remediation and the history purge plan.
  4. Fix the code to read from the environment, re-sweep, confirm the finding is sealed.