Remove repository exposure — history cleanup with filter-repo

The history rewrite is the third step, after disable and rotation. It removes the leaked credential from the repository’s future: every commit, every tag, every ref. It does not remove the credential from the attacker’s memory, the cloud audit log, or any clone already taken.

The rewrite pipeline

A three-step pipeline:

flowchart LR
    A["expressions.txt with old strings"] --> B["filter-repo --replace-text"]
    B --> C["rewritten history"]
    C --> D["reflog expire --expire=now --all"]
    D --> E["gc --prune=now --aggressive"]
    E --> F["clean local clone"]
    F --> G["force-push to central repo"]
    G --> H["rewrite complete"]

• Replace. git filter-repo --replace-text expressions.txt rewrites every matching commit.
• Expire. git reflog expire --expire=now --all expires every reflog entry.
• Prune. git gc --prune=now --aggressive removes unreachable objects.

The expressions file

Each line is a literal or regex, separated from its replacement by ==>:

AKIAIOSFODNN7EXAMPLE==>REDACTED-AWS-KEY
sa-prod-[a-z0-9]+@project-id.iam.gserviceaccount.com==>REDACTED-SA-EMAIL
postgres://app:s3cr3t-prod-pw@db.internal:5432/app==>REDACTED-DB-URL

The filter-repo command

Run from a fresh clone (the rewrite is destructive):

# Fresh clone of the repository to be rewritten
git clone "$REPO_URL" rewrite-workdir
cd rewrite-workdir

# Rewrite every commit matching the patterns
git filter-repo --replace-text /tmp/leak-redact/expressions.txt

# Expire every reflog entry so the old objects are unreachable
git reflog expire --expire=now --all

# Prune the unreachable objects from the local object store
git gc --prune=now --aggressive

The force-push

The rewrite produces a new history. The central repository must be updated:

git push --force-with-lease origin --all
git push --force-with-lease origin --tags

The force-push is the moment the rewrite becomes visible to every consumer. Clones that pull after the force-push see the rewritten history; clones that do not pull continue to see the old history.

Coordinating the rewrite

• Active contributors. Every developer must re-clone after the force-push. A developer pushing to the old history re-introduces the leaked commit.
• CI runners. Every runner must clear its workspace and re-checkout.
• Mirrors and backups. Every mirror must be paused for the rewrite and re-synced after.

Failure modes

• Partial rewrite. The expressions file missed a variant. Extend and re-run from a fresh clone.
• Uncoordinated force-push. Central rewritten but clones are not. Run the coordination list.
• Forgotten forks. A public fork retains the old history. The secret is permanently exposed.

Production discipline

1. Rotate before rewrite. The rewrite is detective hygiene; the rotation is the fix.
2. Fresh clone for the rewrite. Local work is lost when the rewrite changes the SHAs.
3. Coordinate before force-push. Consumers must be notified; otherwise the rewrite is undone.

Cross-course references

• Linux for Production Sysadmins - Part XXXIV (KeyMgmt) covers file-level scrubbing.
• Ansible for Production Sysadmins - Part XXXVII (RepoArch) covers backup and mirror patterns.
• Terraform for Production Sysadmins - Part XV (CredentialRotation) covers rotation patterns.

Quiz