Secret Scanning, Push Protection, Custom Patterns, Bypass Controls, and Incident Response: Concepts, Architecture, and Mental Model

1. The problem: the secret is the security object, not the line of Git history

Chapter 20 taught how workflows should receive credentials. Chapter 24 handles the failure case: a credential appears somewhere it should not. The dangerous beginner instinct is to delete the line, amend the commit, and declare victory. That changes repository presentation, but it does not invalidate a copied credential. If an attacker, crawler, collaborator, log collector, fork, or provider has already seen the value, the credential remains usable until the issuing system revokes or rotates it.

GitHub therefore provides two complementary classes of control. Secret scanning searches existing content and creates evidence after a match is found. Push protection examines content at a write boundary and can block a secret before it reaches the repository. Neither replaces provider-side revocation. Detection tells you where the exposure is; the issuing provider controls whether the credential can still authenticate.

2. Mental model: prevention, detection, containment, cleanup

              flowchart TD
                W["Developer / API / GitHub UI write"] -->|candidate content| P["Push protection"]
                P -->|safe| R["Repository / hosted surface"]
                P -->|supported secret| B["Blocked write or governed bypass"]
                R -->|historical + hosted-content scan| S["Secret scanning"]
                S -->|match| A["Alert / partner notification"]
                A -->|identify provider + owner| V["Revoke or rotate credential"]
                V -->|contain and assess use| C["Incident evidence"]
                C -->|remove exposed content if useful| H["Content cleanup / optional history rewrite"]
                H -->|verify| Z["Closed incident + prevention improvement"]
            

The first arrow is a proposed write: a Git push, web edit/upload, or supported API operation. Push protection can stop that write before repository state changes. If content reaches a GitHub surface, secret scanning examines Git history and supported hosted content. A match creates a user alert, a push-protection alert, or a partner notification depending on the pattern and feature. The critical control then leaves GitHub: the credential issuer must revoke or rotate the secret. Only after access is contained do you decide how much repository cleanup is justified.

The last arrow matters operationally. “Closed” means the old credential is unusable, its possible use was assessed, dependent systems were migrated, residual exposed copies were handled, and prevention was improved. It does not mean the repository’s current default branch happens to look clean.

3. Secret scanning: historical and hosted-content detection

Secret scanning examines the entire Git history on all branches and rescans when GitHub adds new supported secret types. Current GitHub.com scanning also covers titles/descriptions/comments in issues and pull requests, GitHub Discussions, wikis, and secret gists. An incident responder must therefore ask “where is this credential visible?” rather than assuming every leak is a blob in a Git commit.

A secret-scanning alert is a GitHub security object with state, type, locations, resolution, and sometimes validity/metadata. The alert is evidence about exposure; it is not the credential itself and should be retrieved with literal-secret hiding whenever possible.

4. Push protection: a write-path control

Push protection evaluates supported secret patterns before the write is accepted. Current GitHub behavior covers command-line pushes, commits and uploads in the web UI, supported REST writes, and some GitHub MCP interactions. A block means the repository has not yet accepted that attempted content. The safest response is to remove the value and retry; there is no security benefit to bypassing a known real secret merely because the secret will be rotated later.

5. Bypass is an exception workflow, not a detector failure

A false positive, a non-sensitive test value, or trusted migration automation can justify an exception. But routine bypass destroys the value of prevention. Repository push protection can require a reason, and delegated bypass can separate the person requesting an exception from the person approving it. Current delegated-bypass requests expire after seven days, which reinforces the idea that an exception is a short-lived decision, not permanent permission.

6. Read-only inspection before changing anything

Before enabling, disabling, or testing a protection, inspect the repository and account state. The UI remains useful because it exposes current Secret Protection configuration, while the REST repository object gives machine-readable security settings and the secret-scanning API gives alert state. Do not print literal secret values while inspecting alerts.

REPO=OWNER/REPO

gh repo view "$REPO" --json nameWithOwner,visibility,defaultBranchRef,url

gh api -H "X-GitHub-Api-Version: 2026-03-10" "repos/$REPO" \
  --jq '{visibility,security_and_analysis}'

# When alert access is available, hide literal values in automation.
gh api --paginate -H "X-GitHub-Api-Version: 2026-03-10" \
  "repos/$REPO/secret-scanning/alerts?hide_secret=true&per_page=100" \
  --jq '.[] | {number,state,secret_type,validity,resolution,is_publicly_leaked,is_multi_repo,push_protection_bypassed}'

An empty alert list is evidence that the API returned no current matches under your visibility—not proof that no credential exists anywhere. A 404/403 can mean different things: unavailable feature, wrong repository, insufficient role/token permission, or product/version mismatch. Diagnose those before changing policy.

7. Incident response: the order is the control

8. Why this matters in DevOps

CI/CD systems concentrate credentials: package tokens, deployment identities, signing keys, webhook secrets, API credentials, and service accounts. A single leaked high-privilege credential can cross repository and environment boundaries. Secret scanning and push protection therefore sit at the same trust boundary as workflow permissions and runner isolation: they reduce the probability and blast radius of automation compromise.

The production objective is not “zero secret alerts at any cost.” It is a measurable system where supported writes are blocked early, alerts are triaged quickly, live credentials are revoked first, exceptions are auditable, non-Git surfaces are included in incident scope, and custom detection does not create more bypass behavior than it prevents.

Knowledge check

Summary

Secret scanning detects historical and hosted-content exposure; push protection prevents supported secrets from entering protected write paths; validity and pattern metadata help prioritize; bypass is an exception workflow; and the incident begins with provider-side revocation/rotation, not Git surgery.

Next you will exercise those boundaries in a disposable public repository using a GitHub-published dummy token that cannot authenticate.

Official references

• Secret scanning concepts
• Push protection concepts
• Supported secret scanning patterns
• Validity checks
• REST API for secret scanning
• Removing sensitive data from a repository