This guide provides a comprehensive, multi-stage process to detect, confirm the exposure of, and immediately revoke sensitive API keys accidentally committed to public GitHub repositories.
๐ ๏ธ Tools & Prerequisites: Administrative access to the GitHub account owner's credentials. Access to a local machine with Git installed (Linux/macOS recommended). Credentials for all services whose keys might be exposed (e.g., AWS, Stripe, OpenAI).
1. Executive Overview / Summary
When developers accidentally commit sensitive credentials like API keys, database passwords, or access tokens to public GitHub repositories, it creates a severe security vulnerability. This guide outlines the necessary steps to quickly identify these leaks, revoke the compromised keys at the source service provider, and permanently scrub them from your Git history.
โ ๏ธ Security Warning: Treat this process as an emergency response. Speed is critical for minimizing potential damage (financial loss, data breach).
2. Problem Overview & Error Symptoms
The primary symptom is the public accessibility of plaintext secrets within a repository's commit history or README files. While the code might appear functional on your local machine, anyone with read access to the repo can extract and use these keys against live services.
- Key Found in Commit Logs: Viewing
git log -30 reveals credentials. - Key Visible in Documentation: A README or configuration file explicitly lists an API key.
- Unexpected Service Usage: You receive billing alerts or rate-limit errors from external services using the exposed keys.
๐ Root Cause & Diagnostic Overview: The root cause is improper secret management practices, specifically committing runtime secrets (which should be loaded via environment variables) directly into version control. The mechanism of exposure relies on Git's immutable history; deleting a file only removes it from the current state, not from past commits.
3. Root Causes & Technical Mechanisms
The danger lies in two areas: 1) Lack of Pre-Commit Hooks: Not using tools like pre-commit hooks to scan for secrets before they even enter the staging area. 2) History Pollution: Even if you delete the key from the latest commit, Git retains it forever in the object database unless explicitly purged from history.
STEP 1Immediate Credential Revocation (The Highest Priority)
Before touching any code, assume the key is compromised. You must invalidate it at the source service provider.
- Identify all services linked to the exposed keys (e.g., AWS, Stripe, OpenAI).
- Navigate to the Credentials/API Keys management dashboard for each service.
- Locate the specific keys and use the "Revoke," "Delete," or "Generate New" function immediately.
- Best Practice: If a key was exposed, assume it's been used by malicious actors. Generate entirely new keys for all affected services.
STEP 2Local Repository History Scrubbing (The Technical Fix)
We must rewrite the repository history to excise the committed secrets permanently. Standard git rm is insufficient.
# Option A: Recommended for most users (using BFG or git filter-repo)
# Install tool first (e.g., pip install bfgcrypt)
bfg --delete-files api_key_name.txt your-repo-name/
If using git filter-repo:
git filter-repo --path path/to/secretfile --invert-paths
# OR if the key is embedded in a file:
git filter-repo --strip-blobs-containing "YOUR_EXPOSED_KEY_STRING"
STEP 3Forcing the Clean History to GitHub
After rewriting local history, you must overwrite the remote repository's history. This is a destructive operation and requires force pushing.
- Ensure all collaborators are aware of this forced push, as it will disrupt their local copies.
- In your main branch directory:
git push origin --force --all - If you have multiple branches to clean:
git push origin --force --tags
STEP 4Implementing Prevention (The Long-Term Fix)
To prevent recurrence, integrate automated scanning into your workflow.
4. Troubleshooting & Common Pitfalls Matrix
TROUBLESHOOTINGCommon Pitfalls & Advanced Diagnostics
If the key still appears after Step 3, it means you missed a commit or branch. Never assume one command fixes everything.
- Pitfall: Not cleaning all branches.
git for-each-ref --format='%(refname)' refs/heads/ | xargs -I {} git checkout {} && bfg ... - Pitfall: Relying on GitHub's "History Cleanup". GitHub only shows the current state; you must rewrite history locally and push.
- Diagnostic Check: Run
git log --all --full-history --grep="secret_string" to confirm if any commit object still references the pattern before forcing the clean push.
FINAL STEPVerification, Results & Long-Term Stability Validation
After successfully force-pushing and revoking keys, validation is crucial.