Secrets in the repository: gitleaks in pre-commit and CI and what to do if there is a leak
If the key has already leaked, first this
The order of actions is more important than the tools, so let's start from the end.
- 1.Revoke and reissue the key from the provider. Immediately, before clearing the history and analysis. Public repositories are constantly scanned by bots, and a key that ends up in a public commit should be considered compromised from the moment of pushing.
- 2.Update the key in all environments (CI secrets, hosting variables, secrets manager) and restart the services.
- 3.Check the key usage log with your provider: calls from unfamiliar addresses, unusual volumes, created resources. For cloud keys - new instances and IAM users.
- 4.Only then decide whether to clear the history. You can rewrite it via
git filter-repo, but you do not control clones, forks, CI caches and copies of mirror services. Removing from history is about hygiene, not about fixing a leak. If a key is revoked, it is harmless no matter where it is.
A common mistake is to delete the file with a new commit and consider the problem solved. The value remains in history and is found with one command git log -p.
Prevention: gitleaks locally
gitleaks searches the code and history for strings similar to the keys of known services and high-entropy values according to a set of rules. Connection via pre-commit framework:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.30.1 # конкретный тег; pre-commit autoupdate обновит его
hooks:
- id: gitleakspip install pre-commit # или brew install pre-commit pre-commit install # ставит хук в .git/hooks pre-commit run gitleaks --all-files
The hook only checks what you commit, so it's fast. But it is local: the colleague who did not run pre-commit install does not have it, and it is disabled by git commit --no-verify. Therefore, pre-commit is a convenience for the developer, and the real barrier is verification in CI.
One-time check of the entire history of an existing repository (in versions 8.19 and later the commands are called git and dir; the old detect and protect are retained for compatibility):
gitleaks git --redact -v .
The --redact flag hides the found values in the output - without it, the report itself becomes a leak if it is copied into a ticket.
Validation in CI
# .github/workflows/secrets.yml
name: secrets
on: [pull_request, push]
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 }}For organizational repositories, gitleaks-action requires a license key (free, available upon request) in the GITLEAKS_LICENSE variable. An alternative without a key is to run the binary itself or the gitleaks Docker image in the run step.
Make this task a mandatory check in the branch protection rules. Then a secret leaked locally will stop at PR, even before it gets to the main branch.
False positives
Test fixtures, example keys from documentation, and hashes in lock files sometimes look like secrets. Options:
- The
gitleaks:allowcomment in the line is a targeted exception, visible in the review. - File
.gitleaksignorewith fingerprints of specific findings from the report. - Own
.gitleaks.toml, expanding the standard rules and setting exceptions along the paths.
Don't exclude entire directories like config/ - that's where the secrets end up.
GitHub push protection
GitHub has built-in secret scanning with push blocking for known token formats. It is available for free for public repositories, and for private ones as part of the paid GitHub Secret Protection. It complements gitleaks: it works on the server side and cannot be missed by a flag, but it only knows the formats of GitHub partners and does not see your own secrets of any kind.
How to prevent leaks in principle
.env*in.gitignorefrom the first commit, in the repository there is only.env.examplewith empty values.- Keys with minimal rights and separate for each environment: leaking a test key should not open production.
- Secrets in CI - through the built-in secrets store, never in YAML.
- Attention to logs: the values of environment variables printed when debugging the build remain in the CI logs.
What not to do
- Don't "encrypt" the base64 key before committing. Scanners will not always catch this, but the attacker will decode it in a second.
- Do not delay rotation until it is clear whether someone has used the key. Clarification takes hours, rotation takes minutes.
- Do not rewrite the history of a shared thread silently. Colleagues with local copies will revert old commits with the next push; agree and ask to re-clone the repository.