About using rulesets for code scanning merge protection
Note
- Merge protection with rulesets is not related to status checks. For more information about status checks, see About status checks.
- Merge protection with rulesets will not apply to merge queue groups or Dependabot pull requests analyzed by default setup.
You can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
-
A required tool found a code scanning alert of a severity that is defined in a ruleset.
-
A required code scanning tool's analysis is still in progress.
-
A required code scanning tool is not configured for the repository.
Typically you should use rulesets target long-lived feature branches, where you would like to guarantee that code has been analyzed before pull requests can be merged.
Configuring a code scanning rule will not automatically enable code scanning. For more information about how to enable code scanning, see Configuring default setup for code scanning.
For more information about code scanning alerts, see About code scanning alerts.
You can set merge protection with rulesets at the repository or organization levels, and for repositories configured with either default setup or advanced setup. You can also use the REST API to set merge protection with rulesets.
For more information about rulesets, see About rulesets.
Creating a merge protection ruleset for a repository
-
On GitHub, navigate to the main page of the repository.
-
Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.
-
In the left sidebar, under "Code and automation," click Rules, then click Rulesets.
-
Click New ruleset.
-
To create a ruleset targeting branches, click New branch ruleset.
-
Under "Ruleset name," type a name for the ruleset.
-
Optionally, to change the default enforcement status, click Disabled and select an enforcement status. For more information about enforcement statuses, see About rulesets.
-
Under "Branch protections", select Require code scanning results.
-
Under "Required tools and alert thresholds", click Add tool and select a code scanning tool with the dropdown. For example, "CodeQL".
-
Next to the name of a code scanning tool:
- Click Alerts and select one of: None, Errors, Errors and Warnings or All.
- Click Security alerts and select one of: None, Critical, High or higher, Medium or higher, or All.
For more information about alert severity and security severity levels, see About code scanning alerts.
For more information about managing rulesets in a repository, see Managing rulesets for a repository.
Creating a merge protection ruleset for all repositories in an organization
-
In the upper-right corner of GitHub, select your profile photo, then click Your organizations.
-
Next to the organization, click Settings.
-
In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Rulesets.
-
Click New ruleset.
-
To create a ruleset targeting branches, click New branch ruleset.
-
Under "Ruleset name," type a name for the ruleset.
-
Optionally, to change the default enforcement status, click Disabled and select an enforcement status. For more information about enforcement statuses, see About rulesets.
-
Under "Branch protections", select Require code scanning results.
-
Under "Required tools and alert thresholds", click Add tool and select a code scanning tool with the dropdown. For example, "CodeQL".
-
Next to the name of a code scanning tool:
- Click Alerts and select one of: None, Errors, Errors and Warnings or All.
- Click Security alerts and select one of: None, Critical, High or higher, Medium or higher, or All.
For more information about alert severity and security severity levels, see About code scanning alerts.
For more information about managing rulesets for repositories in an organization, see Managing rulesets for repositories in your organization.
Creating a merge protection ruleset with the REST API
You can use the REST API to create a ruleset with the code_scanning rule, which allows you to define specific tools and set alert thresholds. For more information, see REST API endpoints for rules.