How-To Guide

How to Enable Secret Scanning

Automatic detection of exposed credentials

TL;DR

TL;DR: Enable GitHub secret scanning in your repository settings. Set up pre-commit hooks with detect-secrets or gitleaks to catch secrets before they're committed. Add secret scanning to your CI/CD pipeline as a final safety net. All three layers together provide defense in depth.

Defense in Depth Strategy

Layer	When	Tool
Pre-commit hook	Before commit	detect-secrets, gitleaks
CI/CD pipeline	On push/PR	GitHub Actions, GitLab CI
Repository scanning	After push	GitHub Secret Scanning

Option 1: GitHub Secret Scanning

GitHub automatically scans public repositories. For private repos on Team/Enterprise plans:

Enable in repository settings

Go to your repository on GitHub
Click Settings → Security → Code security and analysis
Enable Secret scanning
Enable Push protection to block pushes with secrets

Review alerts

When secrets are detected, GitHub creates alerts in Security → Secret scanning alerts. You'll also receive email notifications.

Push Protection: When enabled, GitHub blocks pushes that contain detected secrets, giving you a chance to remove them before they enter the repository.

Option 2: Pre-commit Hooks with detect-secrets

Catch secrets before they ever enter git history:

Install detect-secrets

pip install detect-secrets pre-commit

Create baseline file

# Scan your codebase and create a baseline
detect-secrets scan > .secrets.baseline

Review the baseline file and remove any false positives.

Configure pre-commit

Create .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.4.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']
        exclude: package-lock.json

Install the hook

pre-commit install

Now, every commit will be scanned for new secrets.

Option 3: Gitleaks

Another popular option, especially for CI/CD:

Local Usage

# Install (macOS)
brew install gitleaks

# Install (go)
go install github.com/gitleaks/gitleaks/v8@latest

# Scan current directory
gitleaks detect --source . -v

# Scan git history
gitleaks detect --source . --log-opts="--all"

Pre-commit Hook

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

Option 4: CI/CD Pipeline Integration

GitHub Actions

name: Security Scan

on: [push, pull_request]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Using TruffleHog

name: TruffleHog Scan

on: [push, pull_request]

jobs:
  trufflehog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: TruffleHog
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: main
          head: HEAD

Handling False Positives

Sometimes scanners flag test data or example values. Here's how to handle them:

With detect-secrets

# Update baseline to include known false positives
detect-secrets scan --baseline .secrets.baseline

# Audit the baseline interactively
detect-secrets audit .secrets.baseline

With gitleaks

Create a .gitleaks.toml configuration file:

[allowlist]
description = "Allow example and test files"
paths = [
  '''\.env\.example$''',
  '''test/fixtures/''',
]
regexes = [
  '''example_api_key''',
  '''test_secret''',
]

What types of secrets can these tools detect?

Most tools detect API keys (Stripe, AWS, OpenAI), access tokens (GitHub, GitLab), private keys, database connection strings, and more. They use pattern matching and entropy analysis to identify potential secrets.

Will secret scanning slow down my commits?

Pre-commit hooks typically add 1-3 seconds to each commit. CI/CD scanning runs in parallel with other checks. The small time cost is worth the protection against leaked credentials.

What should I do when a secret is detected?

If detected before commit: remove it and use environment variables instead. If already pushed: rotate the credential immediately, then clean git history if needed. Treat any pushed secret as compromised.