Secret Scanning — Playbook

In one sentence

Secret Scanning is GitHub's detection feature that automatically finds API keys, tokens, and connection strings lurking in your repository.

Secrets already committed get an alert; secrets about to be committed are blocked at `git push` time by Push protection. Stopping leaks before they happen is the core strategy.

Detection vs Push protection — what’s the difference?

Secret Scanning operates in two modes. You should enable both.

Feature	When does it run?	What does it do?	Scope
🔍 Secret scanning alerts	After commit (including history, continuously)	Notifies you of detected secrets in the Security tab	Commit history, Issues, PRs, descriptions, Wikis
🛡️ Push protection	Right before `git push`	Rejects pushes containing secrets (bypass is possible)	Incoming changes only
✅ Validity checks	When an alert fires	Asks the provider API whether the secret is still active	Select supported providers (AWS, GitHub, Slack, and others)

🔑 Alerts = find secrets already in the repo; Push protection = prevent them from getting in at all. Push protection is the most effective measure (no history rewriting needed).

📘 Details: About secret scanning ↗ · About push protection ↗

What gets detected

🏷️ Provider patterns — Regex patterns registered by 200+ partners including AWS, Azure, GCP, Stripe, Slack, OpenAI, and GitHub PATs. Extremely low false-positive rate
🧪 Generic / non-provider patterns — password = "...", HTTP basic auth, generic API key-like strings. AI-based detection (Copilot Secret Scanning) can also be enabled
🛠️ Custom patterns — Define your own regex for proprietary token formats (requires GHAS)
📚 Scope — Not just code: Issues, PRs, commit messages, descriptions, Wikis, and Gists are all scanned

🤖 Generic secrets and AI detection tend to produce more false positives. Pairing them with Push protection means things get stopped at the moment someone tries to commit them — much easier to operate.

📘 Details: Supported secrets (provider patterns) ↗ · Defining custom patterns ↗

Response flow when a secret is exposed

When a secret is found, remediation matters more than detection.

🚨 Rotate / revoke immediately — removing it from the repository is not enough (it remains in history and in other people’s clones)
📣 GitHub notifies you — providers enrolled in the partner program may automatically invalidate the secret (AWS, GitHub PATs, and others)
🧹 Close the alert — mark it as Revoked, False positive, or Used in tests
🛡️ Enable Push protection to prevent recurrence

Getting started (fastest path)

Step 1 — Enable Push protection (highest priority first)

Repo → Settings → Code security
  ✅ Secret scanning
  ✅ Push protection

Public repos have this on by default and completely free. Repo-level push protection for private repos requires Secret Protection / GHAS — but individual user opt-in is free on all plans (User → Settings → Code security and analysis).

Step 2 — Scan for existing leaks

Once enabled, past commit history is automatically scanned. Alerts will appear in the Security tab — work through them from the top, rotating each secret.

Step 3 — Add custom patterns

Repo or Org → Settings → Code security → Secret scanning → Custom patterns

Register your own token format with a regex. Free for public repos; private repos require GHAS / Secret Protection. Use the dry-run feature to check for false positives before going live.

Step 4 — Enable org-wide / enterprise-wide

Use default settings in Org → Settings → Code security to apply to new and existing repositories at once.

📘 Details: Enabling secret scanning for your repo ↗

Eligibility and pricing

Feature	Public repo	Private repo (No GHAS / Secret Protection)	Private repo (With GHAS / Secret Protection)
Push protection (user personal opt-in)	✅ Free	✅ Free (since 2024)	✅
Push protection (repo / org level)	✅ Free	❌	✅
Secret scanning alerts	✅ Free	❌	✅
Partner secret invalidation	✅ Automatic	❌	✅ Automatic
Validity checks	✅ Free	❌	✅
Custom patterns	✅ Free	❌	✅
AI detection (generic)	✅ Free	❌	✅

💰 In 2025, GHAS was split — if you only need secret scanning, Secret Protection ($19/month/active committer) is enough (no full GHAS contract required). Combine with GitHub Code Security if you also want CodeQL.
🆓 Individuals can enable user push protection via Settings → Code security — this warns even on private repos without any license. Recommending this to all employees is the fastest way to prevent accidents.
🛡️ Push protection at the repo/org level is completely free and on by default for public repos. A Secret Protection / GHAS license is only needed when you want to enforce it org-wide on private / internal repos. See About push protection ↗.

📘 Details:

Secret Risk Assessment (free inventory scan)

Secret Risk Assessment performs a one-time scan of every repository in your org (public, private, internal, and archived) to make visible "what secrets are hiding and where."

No GHAS / Secret Protection required — completely free (since 2025), available to all Team and Enterprise orgs. Perfect for a pre-purchase inventory or an executive security report.

🔎 Scope — all repos in the org (any visibility), including archived repos
📊 Output — aggregated report showing secret type, count, and how many are in each repo (individual secret values are not exposed)
🕒 Frequency — a single point-in-time scan; not continuous monitoring (buy Secret Protection for ongoing coverage)
🔐 Privacy — detected secret values are not stored by GitHub. Only statistics are visible to org admins
🚀 How to run — Org → Settings → Code security → Secret risk assessment → Run assessment

📊 Use this first when you want to “just know how many secrets are leaking across the org” or “need numbers for a budget proposal.” Review the results to decide whether to adopt Secret Protection.

📘 Details: Enabling Secret Risk Assessment ↗