Skip to content

ADR 005: Implement Secret Leak Detection via Gitleaks

  • Status: Accepted
  • Date: 2026-02-14
  • Author: Victoria Cheng

Context and Problem Statement

Accidental commits of sensitive information (API keys, passwords, tokens) pose a significant security risk. Once committed to a repository, secrets are difficult to fully revoke and can be easily discovered by malicious actors. We need an automated way to prevent secrets from being introduced into the codebase.

Decision Outcome

We will implement a reusable GitHub Action check-secret-leaks that uses Gitleaks to scan pull requests for sensitive information.

Logic

The workflow will use the gitleaks protect command to scan the changes introduced in a Pull Request.

  • Incremental Scanning: By default, it will only scan the commits included in the PR to avoid blocking on existing historical debt.
  • Fail-Fast: If a leak is detected, the check will fail, preventing the PR from being merged until the secret is removed and the history is cleaned.
  • Configuration: A .gitleaks.toml file can be used for custom rules or allowlisting if necessary.

Alternatives Considered but Rejected

  • Custom Regex Scripts: Rejected as they are difficult to maintain and prone to missing complex patterns that specialized tools like Gitleaks handle natively.
  • GitHub Secret Scanning (Standard): While useful, it often acts after the secret has been pushed. Gitleaks integrated as a PR gate provides a more proactive "Shift Left" approach.
  • TruffleHog: A strong alternative, but Gitleaks is preferred for its lightweight binary, performance, and wide adoption in DevOps workflows.

Consequences

Positive

  • Risk Reduction: Dramatically reduces the risk of accidental secret exposure.
  • Standardized Security: Standardizes security checks across all repositories using this platform action.
  • Good Practices: Encourages developers to use environment variables or secret managers.

Negative

  • False Positives: Potential for false positives which may require manual intervention (allowlisting).
  • CI Latency: Adds a small amount of latency to the PR check process.

Verification

  • [x] Functional Test: Create a PR containing a dummy secret and verify that the workflow fails.
  • [x] Clean PR: Verify that PRs without secrets pass successfully.
  • [x] Log Output: Ensure detected leaks are clearly identified in the Gitleaks output for easy remediation.