Prevention by design — pre-commit hooks, CI gates, and secrets that never reach the repository

The response to a secret leak is bounded by the channels the team controls. The prevention is the only step that prevents the next leak from leaving the team trust boundary. The layered posture keeps the secret out of the repository, the engineer, the CI pipeline, the forge, and the production system. The five layers are pre-commit hook, pre-receive hook, CI gate, secret manager, and training.

The layered posture

The production posture is five layers, each catching the bypass of the previous:

flowchart LR
    A["engineer writes code"] --> B["pre-commit hook (local)"]
    B -->|"clean"| C["git commit"]
    B -->|"finding"| Z["block commit"]
    C --> D["git push"]
    D --> E["pre-receive hook (forge)"]
    E -->|"clean"| F["central repository"]
    E -->|"finding"| Y["block push"]
    F --> G["CI gate (merge)"]
    G -->|"clean"| H["merge to main"]
    G -->|"finding"| X["fail build"]
    H --> I["secret manager (consumer)"]
    I --> J["production system"]

• Pre-commit hook (engineer’s machine). Runs gitleaks protect --staged --verbose before the commit is created. Fastest catch; skippable with --no-verify.
• Pre-receive hook (forge or mirror). Runs on every push. Cheapest catch; needs forge support.
• CI gate (pipeline). Runs on every pull request. Most visible catch; the commit lands on the branch before the gate runs.
• Secret manager (central store). The only source of the secret; the consumer reads from the secret manager at runtime.
• Training (the engineer). The engineer knows the workflow; the engineer reaches for the manager rather than the file.

The pre-commit hook

The pre-commit hook is the fastest catch. The hook runs on the engineer’s machine before the commit is created. The implementation is the pre-commit framework (a Python tool that manages Git hooks) and the gitleaks hook:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks

The pre-commit install command installs the hook in the engineer’s .git/hooks/pre-commit. The hook runs gitleaks protect --staged --verbose on every git commit. The commit is blocked when the hook finds a secret; the commit proceeds when the hook is clean.

The hook can be skipped with git commit --no-verify. The skip is the bypass; the bypass is the reason the other layers exist. The team policy is to treat a --no-verify skip as a reviewable offence.

The CI gate

The CI gate is the merge-blocking step. The shape in GitHub Actions:

name: secret-scan
on:
  pull_request:
    branches: [main]
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 }

The step fails the build when gitleaks finds a secret; the failed build locks the merge; the engineer is forced to either remove the secret or escalate. The override requires a senior reviewer’s approval and is logged in the audit trail.

The CI gate is the most visible layer. The CI gate is the layer the engineer sees when the workflow is broken; the CI gate is the layer the team reviews in the postmortem. The CI gate is the layer the team tunes when the ruleset produces false positives.

The secret manager

The secret manager is the central store. The secret manager is the only source of the secret; the consumer reads from the secret manager at runtime. The pattern:

export AWS_ACCESS_KEY_ID=$(vault kv get -field=access_key secret/aws/prod)
export AWS_SECRET_ACCESS_KEY=$(vault kv get -field=secret_key secret/aws/prod)

The secret never reaches a file in the repository; the secret reaches the consumer as a process environment variable. The process is restarted when the secret rotates; the new process reads the new secret from the manager.

The implementations:

• HashiCorp Vault. The reference implementation; the broadest feature set; the most operational complexity.
• AWS Secrets Manager / GCP Secret Manager / Azure Key Vault. The cloud-native managers; the IAM integration is natural.
• SOPS-encrypted files in the repository. The secret is encrypted in the repository; the encryption key is in the secret manager; the consumer decrypts at runtime.
• GitHub Actions Secrets / GitLab CI Variables. The pipeline-level manager; the secret is available to the pipeline as an environment variable.

The pattern is the same in all four: the secret is in the manager, the consumer reads from the manager, the secret never reaches a file in the repository.

The training

The training is the muscle memory. The training is the engineer who reaches for the manager because the manager is the workflow. The training has three components:

• Onboarding. The new engineer reads the team’s secret-management policy; the new engineer installs the pre-commit hook; the new engineer is given access to the secret manager.
• Drills. The team runs a quarterly drill: a fake secret is committed; the drill is detected; the response is rehearsed.
• Postmortems. Every real incident is the basis for an updated training. The postmortem documents the channels that leaked, the steps that caught the leak, the steps that missed; the postmortem is the input to the next drill.

The training is the layer that converts the policy from a document to a muscle memory. The training is the layer the engineer carries between jobs; the training is the layer the team multiplies when the team hires.

Production discipline

1. The secret manager is the only source. The secret is in the manager; the consumer reads from the manager; the secret is never in a file that lives in the repository.
2. The pre-commit hook is non-negotiable. The hook is installed by default; the skip is reviewable; the bypass is the gap the other layers catch.
3. The CI gate is the merge block. The gate fails the build; the failed build blocks the merge; the blocked merge is the visible control.

Cross-course references

• Linux for Production Sysadmins - Part XXXIV (ConfigMgmt) covers the secret manager integration patterns for system credentials.
• Ansible for Production Sysadmins - Part XXXVII (RepoArch) covers the Ansible Vault pattern that is the special case of the secret manager for playbooks.
• Terraform for Production Sysadmins - Parts IX-XII (State) cover the Terraform variable management that the secret manager replaces.

Quiz