git-secrets — Prevent Secrets from Being Committed to Git

Introduction

git-secrets is a tool from AWS Labs that installs Git hooks to prevent you from committing secrets and credentials to your repositories. It scans staged changes, commit messages, and merge candidates against a configurable set of patterns and blocks the operation if a match is found.

What git-secrets Does

• Installs pre-commit, commit-msg, and prepare-commit-msg hooks in Git repositories
• Scans staged file contents and commit messages for secret patterns
• Ships with built-in patterns for AWS access keys, secret keys, and credential files
• Supports custom regex patterns for organization-specific secrets
• Can scan entire repository history to find previously committed secrets

Architecture Overview

git-secrets is a Bash script that integrates with Git's hook system. When you run git secrets --install, it writes hook scripts into .git/hooks that invoke git-secrets --scan before each commit. The scan reads patterns from .gitconfig entries (both local and global), compiles them into grep-compatible expressions, and tests staged content. If a match occurs, the commit is rejected with a descriptive error message.

Self-Hosting & Configuration

• Install via Homebrew, manual script download, or clone from the repository
• Run git secrets --install in each repository to activate hooks
• Use git secrets --register-aws to add standard AWS credential patterns
• Add custom patterns with git secrets --add 'pattern' for project-specific secrets
• Define allowed patterns with git secrets --add --allowed 'safe-pattern' for false positives

Key Features

• Zero dependencies beyond Git and Bash; no external services or network calls
• Works as standard Git hooks, requiring no CI pipeline changes
• Supports global installation to protect all repositories on a machine
• Allowed patterns let you whitelist known-safe strings that match secret patterns
• The --scan-history flag audits the full commit history for previously leaked secrets

Comparison with Similar Tools

• Gitleaks — Go binary with TOML rule config; scans commits and PR diffs, more rule flexibility
• TruffleHog — scans for high-entropy strings and verified credentials; supports multiple source types
• detect-secrets — Yelp's Python tool with a baseline file approach; plugin-based detection
• pre-commit hooks — framework for managing multi-language Git hooks; git-secrets can run within it
• GitHub Secret Scanning — platform-level scanning on GitHub; works post-push, not pre-commit

FAQ

Q: Does git-secrets work on Windows? A: Yes, when using Git Bash or WSL. The tool is a Bash script and requires a Unix-compatible shell.

Q: How do I install hooks for all future repositories? A: Run git secrets --install --global and git secrets --register-aws --global to add hooks and patterns to your global Git config.

Q: What happens when a secret is detected? A: The commit is blocked and git-secrets prints which file and pattern matched, so you can remove the secret before retrying.

Q: Can I use git-secrets in CI? A: Yes. Run git secrets --scan in your CI pipeline to check committed code. Combine with --scan-history for comprehensive auditing.

Sources

• https://github.com/awslabs/git-secrets
• https://aws.amazon.com/blogs/security