rulesets section configures GitHub rulesets, which provide advanced protection for branches and tags. Rulesets offer more flexibility than traditional branch protection rules and can be applied at the organization or repository level.
Basic Configuration
The name of the ruleset.
The target of the ruleset. Can be:
branch- Apply rules to branchestag- Apply rules to tags
The enforcement level of the ruleset.
evaluate allows admins to test rules before enforcing them.disabled- Ruleset is disabledactive- Ruleset is actively enforcedevaluate- Ruleset runs in evaluation mode (not enforced)
Bypass Actors
The actors that can bypass the rules in this ruleset.
The ID of the actor.
The type of actor that can bypass a ruleset:
RepositoryRole- A repository role (e.g., maintain, write)Team- A team IDIntegration- A GitHub App installation IDOrganizationAdmin- Organization administrators (use actor_id: 1)
When the specified actor can bypass the ruleset:
always- Can always bypasspull_request- Can only bypass rules on pull requests
Conditions
Conditions that determine which refs the ruleset applies to.
Parameters for a repository ruleset ref name condition.
Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts:
~DEFAULT_BRANCH- The repository’s default branch~ALL- All branches or tags
Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match.
Only available for organization-level rulesets. Parameters for repository name matching.
Array of repository names or patterns to include. Also accepts
~ALL to include all repositories.Array of repository names or patterns to exclude.
Whether renaming of target repositories is prevented.
Rules
An array of rules to enforce. Each rule is an object with a
type field and optional parameters.Basic Rules
Prevent users from creating matching refs.
Prevent users from updating matching refs.
Prevent users from deleting matching refs.
Prevent merge commits from being pushed to matching refs.
Require commits to be signed.
Pull Request Rule
Require pull requests before merging.
Status Checks Rule
Require status checks to pass before merging.Using
To allow status checks to be managed outside of Safe Settings, use the special override. This prevents Safe Settings from modifying status checks added manually.
Whether pull requests must be tested with the latest code.
Array of status checks that must pass.Each item has:
context(string, required) - The status check nameintegration_id(integer) - The GitHub App integration ID
Using {{EXTERNALLY_DEFINED}}
To allow status checks to be managed outside of Safe Settings, use the special override. This prevents Safe Settings from modifying status checks added manually.Workflows Rule
Require specific workflows to pass before merging.
Required Deployments Rule
Require deployments to specific environments to succeed before merging.
Pattern Rules
Require commit messages to match a pattern.
Require commit author emails to match a pattern.
Require committer emails to match a pattern.
Require branch names to match a pattern.
Require tag names to match a pattern.
Complete Example
Repository vs Organization Rulesets
Rulesets can be defined at two levels:- Repository level: Defined in repository settings files, applies only to that repository
- Organization level: Defined in org-level settings files, can target multiple repositories using
conditions.repository_name