How to enable GitHub secret scanning push protection: Roll it out with controlled bypass and audit evidence

Owning GitHub Secret Protection does not mean pushes are being blocked: repository push protection must be switched on, and once on, every developer with write access can bypass it unless you restrict that. Repository push protection is off by default, so a licence on its own blocks nothing. This runbook shows how to switch it on properly: at repository level for a pilot, through organisation or enterprise security configurations for scale, and through the REST API for automation. It then covers how to restrict bypass with delegated bypass, how to prove coverage and monitor bypasses through the audit log and alert API, and how to roll back without losing evidence. It is for GitHub organisation owners, security managers and platform engineers. For how push protection compares across GitHub, GitLab and Azure DevOps, see the Push Protection Guide.

This is an independent guide from NHI Mgmt Group, based on GitHub Docs pages read on 11 November 2026. GitHub changes menu labels often, so check the current wording if a path below has moved.

Key takeaways

• Licence is not enforcement. Repository push protection needs GitHub Secret Protection and is off by default; it must be enabled per repository or, better, through a security configuration.
• Configurations beat clicking. An organisation security configuration, attached to all repositories and set as the default for new ones, keeps coverage from drifting as repositories are created.
• Restrict bypass before you announce it. By default anyone with write access can bypass by choosing a reason; delegated bypass turns that into a reviewed request.
• Exemptions are a hole, not a convenience. An exempt actor is never blocked, so keep the exempt list to named automation accounts and review it monthly.
• Measure with the API, not the settings page. The repository and alert APIs show which repositories have secret_scanning_push_protection enabled and which alerts came from bypasses (is_bypassed=true).

When you need this

Run this procedure when any of the following is true:

• New licence: the organisation has just bought GitHub Secret Protection (or GitHub Advanced Security) and needs coverage switched on.
• Audit finding: an assessment found credentials in repository history and asked for a preventive control. NIST SP 800-53 IA-5(7) (No Embedded Unencrypted Static Authenticators) is the control most auditors cite.
• Leak response: after a leaked key, as part of lessons learned. The Toyota T-Connect Key Exposure is a reminder that a key pushed to a public repository can sit there for years before anyone notices.
• Coverage drift: push protection is on for some repositories but new repositories are created without it, or teams have switched it off.

Push protection prevents new exposure. It does not find secrets already in history: run history scanning alongside it, as described in the Git Secret Scanning Guide.

Before you start

Treat the token you use for this work as a privileged non-human credential: short expiry, scoped to the organisation, revoked when the rollout ends. See the GitHub Personal Access Tokens Security Guide.

Step-by-step

Phase 1: pilot on a few repositories

1. Pick three to five pilot repositories with active developers, including one with heavy automation and one with test fixtures that look like keys.
2. Enable in the UI: open the repository, click Settings, then in the Security and quality section of the sidebar click Advanced Security. If Secret Protection is not enabled, click Enable next to Secret Protection, then click Enable next to Push protection.
3. Or enable through the API: send PATCH /repos/{owner}/{repo} with a body that sets security_and_analysis.secret_scanning.status and security_and_analysis.secret_scanning_push_protection.status to enabled. Record the previous values from GET /repos/{owner}/{repo} first, so rollback restores the exact state.
4. Test with a known pattern: push a commit containing a revoked or provider-documented test token from a scratch branch and confirm the push is rejected. The remote: output names the secret type, the commit and the file path and line, and gives a URL for bypass.
5. Collect developer feedback for one to two weeks: how often were pushes blocked, how long did removal take, and were any blocks false positives.

Phase 2: restrict bypass

1. Decide the bypass model using the decision table below. For most organisations: delegated bypass with a reviewer team, and no exemptions except named automation.
2. Repository level (pilot): in Settings > Advanced Security, under Push protection, set Who can bypass push protection for secret scanning to Specific roles or teams, then under Bypass list click Add role or team and Add selected. Secret teams cannot be added.
3. Give reviewers a narrow role: create a custom organisation role with the Review and manage secret scanning bypass requests permission and assign it to the reviewer team, rather than making reviewers organisation owners.
4. Exempt only named automation: click Exempt next to an entry only for an account that legitimately writes key-like material, such as a repository migration bot. GitHub's own documentation warns that exemptions may lead to leaked secrets.

Phase 3: scale with a security configuration

1. Create a custom configuration: organisation Settings, then in the Security section open Advanced Security and click Configurations. Create a custom security configuration with secret scanning enabled and push protection Enabled. Under Push protection, set Bypass privileges to Specific actors and add the reviewer team. Click Save configuration.
2. The API equivalent is POST /orgs/{org}/code-security/configurations with secret_protection, secret_scanning and secret_scanning_push_protection set to enabled, secret_scanning_delegated_bypass set to enabled, and secret_scanning_delegated_bypass_options.reviewers listing each reviewer with reviewer_id, reviewer_type (TEAM or ROLE) and mode (ALWAYS, or EXEMPT for exemption). Set enforcement to enforced so repository admins cannot change the settings the configuration controls.
3. Attach in rings: POST /orgs/{org}/code-security/configurations/{configuration_id}/attach with scope set to selected and a list of selected_repository_ids for the first ring, then public, then all_without_configurations (repositories with no configuration yet), and finally all once you are sure no team relies on a different configuration.
4. Cover new repositories: PUT /orgs/{org}/code-security/configurations/{configuration_id}/defaults with default_for_new_repos set to all, or private_and_internal if public repositories use a separate configuration.
5. Enterprise: repeat the pattern from the enterprise Settings > Advanced Security > Configurations, or POST /enterprises/{enterprise}/code-security/configurations/{configuration_id}/attach. A configuration set at organisation or enterprise level disables the repository-level bypass settings, which is the point: teams cannot loosen it locally.

Phase 4: extend what is blocked

1. Custom patterns: for internal token formats, define a custom pattern at organisation or enterprise level, test it against existing history, then opt it into push protection. Patterns with a fixed, unique prefix are far easier to block without false positives.
2. Non-provider (generic) patterns: enable secret_scanning_non_provider_patterns in the configuration to detect structured secrets such as private keys and connection strings, measure false positives from the alerts for a few weeks, then decide whether to enforce them at push.
3. Developer accounts: remind developers that push protection for users (profile Settings > Code security > Push protection for yourself) is on by default for public repositories and should stay on, because it covers personal and open source pushes the organisation does not control.

Choosing the bypass model

Small organisations (one security person, a few dozen repositories) can start with the default model and read every bypass alert, then move to delegated bypass once request volume is known. Large organisations should not enable at scale without delegated bypass and a reviewer rota with a response target, because unanswered requests block releases and push teams to ask for exemptions. Approved bypass requests also allow future commits with the same secret, so reviewers should approve only when the value is genuinely harmless.

Verify it worked

1. Coverage: for each repository, GET /repos/{owner}/{repo} and read security_and_analysis.secret_scanning_push_protection.status. Any repository not enabled is a gap; check whether it is archived, unlicensed or attached to a different configuration.
2. Blocking: repeat the test push in one repository per ring and confirm the rejection, including through the web editor and a file upload, since both are covered entry points.
3. Bypass alerts: GET /orgs/{org}/secret-scanning/alerts?is_bypassed=true returns alerts created by a bypass, with push_protection_bypassed_by, push_protection_bypassed_at and, for delegated bypass, push_protection_bypass_request_reviewer. Combine with state=open and validity=active to find live credentials that someone chose to push.
4. Audit log: confirm the events below appear for your test actions, then build alerts on them in your SIEM. See the GitHub Audit Log Detection Guide.

Metrics that show it is working:

• Coverage: percentage of active repositories with push protection enabled (target 100% of licensed repositories).
• Blocked pushes: pushes blocked per month, which should rise first and then fall as developers adapt.
• Bypass rate: bypasses as a share of blocks, split by reason; a high "used in tests" share deserves sampling.
• Open bypass alerts: count of open alerts with is_bypassed=true and their age; the target is zero older than the rotation SLA.
• Request turnaround: median time from bypass request to decision under delegated bypass.
• Exempt actors: number of exempt accounts, which should stay small and stable.

Rollback and common errors

Rollback: if push protection blocks a release-critical pipeline, do not disable it organisation-wide. In order of preference: approve a delegated bypass request for the specific value; detach only the affected repository from the configuration and set it back to its previous state with PATCH /repos/{owner}/{repo} using the values you recorded in Phase 1; as a last resort set secret_scanning_push_protection to disabled in the configuration. Disabling does not delete existing alerts or audit events, so evidence is preserved. Re-enable within an agreed window and record the exception.

• Setting not visible: the repository is not covered by a Secret Protection licence, or you lack the admin or security manager role.
• Repository settings greyed out: an organisation or enterprise configuration is enforced. Change the configuration, not the repository.
• Bypass URL returns 404: only the user who made the push can use it. Another engineer cannot bypass on their behalf.
• Bypass expired: the push must be retried within three hours of allowing it; after that the developer repeats the process.
• Push still blocked after removing the secret: it remains in an earlier commit in the push. Remove it from every commit, using git commit --amend for the latest commit or an interactive rebase from the earliest affected commit.
• Integration fails with errors after rollout: REST API writes that contain a detected secret are blocked too; fix the integration rather than exempting its account.

Common failure patterns

• Enabled at repository level only: new repositories arrive unprotected because no default configuration was set. Set default_for_new_repos.
• Bypass by reason left as the permanent model: "It's used in tests" closes the alert, so real credentials mislabelled as test data disappear from the open queue.
• Exemptions for convenience: a release bot is exempted because it was blocked once; if its token is stolen, it can push anything. Recent supply chain worms that abused stolen developer tokens, such as the Shai-Hulud npm Worm, show why trusted automation identities need the same controls as people.
• No owner for bypass alerts: alerts open with "I'll fix it later" and nobody rotates. Route them to the team that owns rotation, with the Leaked Credential Response Playbook as the runbook.
• Assuming passwords are blocked: push protection blocks patterns it can identify with confidence. Passwords and random internal secrets need custom patterns with prefixes, or post-push scanning.

Framework mapping

Hardening afterwards

• Prefer credentials that cannot leak usefully: replace long-lived keys in workflows with OIDC federation. See the GitHub Actions OIDC Federation Hardening Guide.
• Run history scanning: push protection does nothing for secrets already committed; triage those with the Developer Secret Scanning Triage process.
• Add a client-side layer: a pre-commit hook keeps secrets out of local history, which saves developers the rebase that a server block forces.
• Review quarterly: bypass list membership, exempt actors, custom patterns enrolled in push protection, and the configuration enforcement setting.

Practitioner checklist

• Confirm Secret Protection licensing and the roles that will make changes.
• Record current security_and_analysis values for every repository before changing anything.
• Pilot on three to five repositories and test blocking through the CLI, web editor and file upload.
• Enable delegated bypass with a reviewer team holding a custom role, not owner rights.
• Create an enforced organisation security configuration and attach it in rings.
• Set the configuration as default for new repositories.
• Keep exemptions to named automation accounts and review them monthly.
• Alert on push protection disable, bypass and configuration change events.
• Track coverage, bypass rate, open bypass alerts and request turnaround monthly.
• Enrol prefixed internal token formats as custom patterns with push protection.

Standards and references

• GitHub Docs: Enabling push protection for your repository
• GitHub Docs: About push protection
• GitHub Docs: Enabling delegated bypass for push protection
• GitHub Docs: REST API endpoints for code security configurations
• GitHub Docs: REST API, Update a repository
• GitHub Docs: REST API endpoints for secret scanning
• GitHub Docs: Audit log events for your organization
• GitHub Docs: Working with push protection from the command line

Related NHI Mgmt Group resources: Push Protection Guide · Git Secret Scanning Guide · GitHub Organisation Security Checklist · Secret Scanning Programme Rollout Plan Template · OWASP NHI Top 10 NHI2 Secret Leakage Guide