Gitleaks Installation Guide: The “Shield” to Prevent Secret and API Key Leaks in Git

The Nightmare of Accidentally “Gifting” Secrets to GitHub

Many of you have likely experienced that cold sweat when receiving an alert email from AWS or Google Cloud in the middle of the night. A single moment of carelessness—committing a .env file containing an Access Key to a public repo—is like handing your house keys to a thief. The terrifying reality is that bots specialized in scanning source code take less than 60 seconds to detect and exploit this information.

The consequences usually hit fast. Your cloud bill can skyrocket to thousands of dollars overnight as hackers hijack your resources for crypto mining. Even worse, customer data could end up for sale on underground forums. To automatically eliminate this risk, Gitleaks is the best tool I have personally experienced.

What is Gitleaks and Why is it Effective?

Fundamentally, Gitleaks is an open-source tool written in Go, making it extremely lightweight and fast. It is designed to hunt for secrets like API keys, passwords, or tokens hiding in your code. The biggest selling point of Gitleaks is its ability to scan the entire commit history—a place where developers often forget secrets even after deleting them in the latest commit.

Its mechanism relies on over 100 default rules. It combines Regex with Entropy checking (measuring string randomness) to accurately identify specific types of credentials such as Stripe, Twilio, or GitHub Tokens. You can use it to clean up old repositories or stop threats right at the local gateway.

Quick Gitleaks Installation Guide

Depending on your operating system, you can choose the most suitable installation method. I recommend using Homebrew or Docker to keep your system clean.

1. Installation on macOS

brew install gitleaks

2. Installation on Linux (Ubuntu/Debian)

If you are using Linux, you can download the binary directly for immediate use:

VERSION=$(curl -s https://api.github.com/repos/gitleaks/gitleaks/releases/latest | grep tag_name | cut -d '"' -f 4)
wget https://github.com/gitleaks/gitleaks/releases/download/${VERSION}/gitleaks_${VERSION:1}_linux_x64.tar.gz
tar -xvzf gitleaks_${VERSION:1}_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/

3. Using with Docker

For those who prefer not to deal with manual installations, Docker is the optimal solution:

docker pull zricethezav/gitleaks:latest

Practical Professional Secret Scanning

Once installed, try checking the project you are currently working on. The results might surprise you.

Scanning the Entire Repository History

Open your terminal in the project directory and run the following command:

gitleaks detect --source . --report-path leaks-report.json -v

Quick explanation of the parameters:

• --source .: Scans all source code in the current directory.
• --report-path: Exports a detailed report to a JSON file for easy tracking.
• -v: Displays details of the code snippet and the commit hash suspected of leaking.

If Gitleaks reports red, you will see exactly which file and which line contains the secret. It’s quite a painful realization if that repo was pushed to GitHub a long time ago.

Stopping Leaks Before Committing

To prevent mistakes from the start, check the changes currently in the staged area:

gitleaks protect --staged -v

Making this a habit will give you more confidence before hitting Enter on a commit command.

Integrating Gitleaks into Your Workflow

Running commands manually is easy to forget. The most sustainable way is to enforce automatic code scanning for the entire team.

Using Pre-commit Hooks

Gitleaks will automatically trigger every time you type git commit. If a secret is detected, it will block the commit immediately. First, install the pre-commit framework using pip:

pip install pre-commit

Next, create a .pre-commit-config.yaml file in the root directory with the following content:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.2
    hooks:
      - id: gitleaks

Finally, run pre-commit install to activate it. From now on, Gitleaks will be your silent bodyguard.

Deploying GitHub Actions

To ensure absolute safety, add a final check on the server side. Create a .github/workflows/gitleaks.yml file so that every Pull Request is automatically scanned:

name: gitleaks
on:
  push:
  pull_request:
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 }}

What to Do if a Secret is Exposed?

Do not panic and simply delete the line of code and commit over it. This is ineffective because the secret remains in the Git history. Follow these 3 steps:

1. Deactivate the secret immediately: Revoke the AWS Key or change the password immediately. Treat the information as if it is already in the hands of bad actors.
2. Clean the history: Use git filter-repo or bfg-repo-cleaner to permanently delete sensitive strings from all past commits.
3. Configure exceptions: If Gitleaks flags a harmless test string as a false positive, add it to .gitleaksignore to skip it in future scans.

Final Thoughts for Developers

Security is not a one-time task; it is a habit that needs to be maintained. Setting up Gitleaks only takes a few minutes but will help you sleep better at night. Don’t wait until the horse has bolted to close the stable door—protect your source code today. Have you tried re-scanning your old projects? You might just find a few API Keys from your intern days!