Secrets management

What counts as a secret?

A secret is any value that lets someone access or change something. If a stranger who found it could log in, read data, spend money or pretend to be your service, it is a secret.

• Passwords and database connection strings that contain a password
• API keys and tokens (payment gateway keys, GitHub tokens, SMS provider keys)
• Cloud access keys (for example an AWS access key ID with its secret access key)
• Private keys: SSH keys, TLS certificate keys, code-signing keys
• Webhook signing secrets, OAuth client secrets, kubeconfig files with credentials

Ordinary configuration, such as a port number or a feature flag, is not secret. Keep the two apart: configuration can live in Git, secrets cannot.

How secrets leak

Public repositories are scanned by automated bots within minutes of a push. If a cloud key is pushed to a public repository, assume it has already been copied.

Prevention: stop it before the push

A pre-commit hook is a small script that Git runs on your machine before it creates a commit. gitleaks is a free open-source scanner that looks for secret patterns. Run it as a hook so a secret never enters history, and again in CI as a safety net. On GitHub, secret scanning finds known token formats in repositories, and push protection blocks a push that contains one.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2          # pin a release tag; update it from time to time
    hooks:
      - id: gitleaks

pip install pre-commit
pre-commit install            # add the hook to this repository
pre-commit run --all-files    # scan everything once
gitleaks git -v               # scan the whole Git history (older versions: gitleaks detect -v)

Where secrets should live

Short-lived credentials and OIDC from CI

A long-lived key stored in CI works until someone leaks it, and then it works for the attacker too. A short-lived credential expires on its own, often within an hour. OIDC (OpenID Connect) lets your CI job prove who it is to the cloud: GitHub Actions issues a signed token that says "this job runs in repository acme/canteen on branch main". The cloud checks the signature and a trust rule, then hands back temporary credentials. No cloud key is stored in GitHub at all.

permissions:
  id-token: write      # allow the job to request an OIDC token
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/canteen-deploy
          aws-region: ap-south-1
      - run: aws sts get-caller-identity   # temporary credentials, no stored key

Rotation

Rotation means replacing a secret with a new one on a schedule, or straight away when someone leaves the team. Automate it: a manual rotation that happens "every year" usually never happens. To rotate without downtime, create the new secret, let the app accept both for a short overlap, switch the app over, then remove the old one. Vault can go further with dynamic secrets: it creates a unique database user for each app instance and deletes it when the lease ends.

After a leak: the order matters

1. Revoke or rotate the secret immediately. This is the only step that stops an attacker.
2. Check the logs for use during the exposure window: cloud audit logs (such as AWS CloudTrail), the provider's dashboard, unusual bills.
3. Clean the history with git filter-repo or BFG Repo-Cleaner and force-push, after warning the team. Remember that forks, clones and caches may still hold the old commits.
4. Fix the cause: add the pre-commit hook, turn on push protection, move the secret to a secret manager.
5. Write a short blameless review so the team learns from it.