Blocking pull request merges that contain secrets

Prevent exposed secrets from reaching protected branches by requiring contributors to resolve secret scanning alerts before merging.

Who can use this feature?

Organization owners, security managers, and organization members with the admin role

GitHub Secret Protection is a set of features within GitHub Advanced Security that is available to the following users:

  • GitHub Team plan users
  • Enterprise organizations on GitHub Enterprise Cloud and GitHub Enterprise Server

In this article

Note

The rule to require secret scanning alerts to be resolved before merging is in public preview and subject to change.

The Require secret scanning alerts are resolved rule is available for rulesets that target branches in repositories. You can use the rule to block a pull request from merging when either of these conditions applies:

  • A secret scanning scan has not completed for the head commit of the pull request.
  • A commit in the pull request introduced an open secret scanning alert that matches a secret type selected in the ruleset.

The rule supports provider, custom, and generic patterns. It does not support AI-detected secrets.

Prerequisites

The repositories that you want to protect must have:

Creating a merge protection ruleset for a repository

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. In the left sidebar, under "Code and automation," click Rulesets, then click Rulesets.

  4. Click New ruleset.

  5. Click New branch ruleset.

  6. Under "Ruleset name," type a name for the ruleset.

  7. Optionally, to change the default enforcement status, click Disabled and select an enforcement status. To target branches or tags, in the "Target branches" or "Target tags" section, select Add a target, then select how you want to include or exclude branches or tags. You can use fnmatch syntax to include or exclude branches or tags based on a pattern. For more information, see Using fnmatch syntax.

You can add multiple targeting criteria to the same ruleset. For example, you could include the default branch, include any branches matching the pattern *feature*, and then specifically exclude a branch matching the pattern not-a-feature.

  1. Under "Branch protections", select Require secret scanning alerts are resolved.
  2. Under "Secret types", select one or more types of secrets that should block merging:
    • Provider patterns
    • Custom patterns
    • Generic patterns To finish creating your ruleset, click Create. If the enforcement status of the ruleset is set to "Active", the ruleset takes effect immediately.

For information about configuring bypass permissions and other ruleset settings, see Creating rulesets for a repository.

Creating a merge protection ruleset for repositories in an organization

  1. In the upper-right corner of GitHub, click your profile picture, then click Organizations.

  2. Select an organization by clicking on it.

  3. Under your organization name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of the tabs in an organization's profile. The "Settings" tab is outlined in dark orange.

  4. In the sidebar, under "Code, planning, and automation", click Repository, then click Rulesets.

  5. Click New ruleset.

  6. Click New branch ruleset.

  7. Under "Ruleset name," type a name for the ruleset.

  8. Optionally, to change the default enforcement status, click Disabled and select an enforcement status.

  9. Under "Target repositories", choose the repositories that the ruleset will apply to. To target branches or tags, in the "Target branches" or "Target tags" section, select Add a target, then select how you want to include or exclude branches or tags. You can use fnmatch syntax to include or exclude branches or tags based on a pattern. For more information, see Using fnmatch syntax.

You can add multiple targeting criteria to the same ruleset. For example, you could include the default branch, include any branches matching the pattern *feature*, and then specifically exclude a branch matching the pattern not-a-feature.

  1. Under "Branch protections", select Require secret scanning alerts are resolved.
  2. Under "Secret types", select one or more types of secrets that should block merging:
    • Provider patterns
    • Custom patterns
    • Generic patterns To finish creating your ruleset, click Create. If the enforcement status of the ruleset is set to "Active", the ruleset takes effect immediately.

For information about configuring bypass permissions and other ruleset settings, see Creating rulesets for repositories in your organization.

Unblocking a pull request

When this rule blocks a pull request because of open alerts, you must resolve each alert that matches the secret types selected in the ruleset. See Resolving alerts from secret scanning.