Introduction
You can create rulesets in your organization to control how users can interact with repositories in your organization. You can control things like who can push commits to a certain branch and how the commits must be formatted, or who can delete or rename a tag. You can also prevent people from renaming repositories.
You can also create push rulesets to block pushes to a private or internal repository and the repository's entire fork network. Push rulesets allow you to block pushes based on file extensions, file path lengths, file and folder paths, and file sizes.
Forks do not inherit branch or tag rulesets from their upstream repositories. However, forks owned by your organization are subject to the rulesets you create, like any other repository.
Forks do inherit push rulesets from their root repository. Push rules apply to the entire fork network for a repository, ensuring every entry point to the repository is protected. For example, if you fork a repository that has push rulesets enabled, the same push rulesets will also apply to your forked repository.
For a forked repository, the only people who have bypass permissions for a push rule are the people who have bypass permissions in the root repository.
Importing prebuilt rulesets
To import one of the prebuilt rulesets by GitHub, see github/ruleset-recipes
.
You can import a ruleset from another repository or organization using a JSON file. This can be useful if you want to apply the same ruleset to multiple repositories or organizations. For more information, see "Managing rulesets for repositories in your organization."
Using fnmatch
syntax
You can use fnmatch
syntax to define patterns to target when you create a ruleset.
You can use the *
wildcard to match any string of characters. Because GitHub uses the File::FNM_PATHNAME
flag for the File.fnmatch
syntax, the *
wildcard does not match directory separators (/
). For example, qa/*
will match all branches beginning with qa/
and containing a single slash, but will not match qa/foo/bar
. You can include any number of slashes after qa
with qa/**/*
, which would match, for example, qa/foo/bar/foobar/hello-world
. You can also extend the qa
string with qa**/**/*
to make the rule more inclusive.
For more information about syntax options, see the fnmatch documentation.
Note: Not all expressions from the fnmatch
syntax are supported in branch protection rules. Please be aware of the following constraints:
- You cannot use the backslash (
\
) character as a quoting character, as GitHub does not support the use of backslashes in branch protection rules. - You can specify character sets within square brackets (
[]
), but you cannot currently complement a set with the^
operator (e.g.,[^charset]
). - Although GitHub supports
File::FNM_PATHNAME
infnmatch
syntax,File::FNM_EXTGLOB
is not supported.
Using regular expressions for commit metadata
When you add metadata restrictions for a ruleset that targets branches or tags, you can use regular expression syntax to define patterns that the relevant metadata, such as the commit message or the branch or tag name, must or must not match.
Metadata restrictions do not accept regex patterns by default. To enable this, select the Must match a given regex pattern restriction when you are creating the metadata restrictions for your ruleset.
Rulesets support RE2 syntax. For more information, see Google's syntax guide. To validate your expressions, you can use the validator on regex101.com, selecting the "Golang" flavor in the left sidebar.
By default, regular expressions in metadata restrictions do not consider multiple lines of text. For example, if you have a multiline commit message, the pattern ^ABC
will be a match if the first line of the message starts with ABC
. To match multiple lines of the message, start your expression with (?m)
.
The negative lookahead assertion, denoted ?!
, is not supported. However, for cases where you need to look for a given string that is not followed by another given string, you can use the positive lookahead assertion, denoted ?
, combined with the "Must not match a given regex pattern" requirement.
Note: If you require contributors to sign off on commits, this may interfere with your regular expression patterns. When someone signs off, GitHub adds a string like Signed-off-by: #AUTHOR-NAME <#AUTHOR-EMAIL>
to the commit message. For more information, see "Managing the commit signoff policy for your organization."
Useful regular expression patterns
The following examples provide useful patterns for commit metadata. To use these patterns, set Requirement to "Must match a given regex pattern".
Ensure branch names are compatible with Windows
You can use the following pattern to ensure that branch names only include numbers, lowercase letters, and the characters -
and _
. This ensures branch names are compatible with operating systems that do not use case-sensitive file systems by default.
\A[0-9a-z-_]$
\A[0-9a-z-_]$
Matches: my-branch
Does not match: myBranch
Ensure tag names use semantic versioning
You can use the following pattern to ensure tag names conform to semantic versioning. For more information, see the documentation on semver.org.
^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
Matches: 1.2.3
, 10.20.30
, 1.1.2-prerelease+meta
Does not match: 1.2
, 1.2-SNAPSHOT
Limit length of lines in commit messages
The Pro Git book recommends limiting the first line of a commit message to around 50 characters.
You can use the following pattern to ensure the first line in a commit message contains 50 characters or fewer.
\A.{1,50}$
\A.{1,50}$
Ensure commit messages start with a resolution and issue number
You can use the following pattern to ensure that commit messages contain the word Resolves:
or Fixes:
, followed by a string like #1234
.
^(Resolves|Fixes): \#[0-9]+$
^(Resolves|Fixes): \#[0-9]+$
Matches: Fixes: #1234
Does not match: Add conditional logic to foo.bar
Enforce conventional commits
You can use the following pattern to ensure that commit messages conform to the Conventional Commits specification. For more information, see conventionalcommits.org.
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)
Matches: feat: allow provided config object to extend other configs
Does not match: Add conditional logic to foo.bar
Using ruleset enforcement statuses
While creating or editing your ruleset, you can use enforcement statuses to configure how your ruleset will be enforced.
You can select any of the following enforcement statuses for your ruleset.
- Active: your ruleset will be enforced upon creation.
- Evaluate: your ruleset will not be enforced, but you will be able to monitor which actions would or would not violate rules on the "Rule Insights" page.
- Disabled: your ruleset will not be enforced or evaluated.
Using "Evaluate" mode is a great option for testing your ruleset without enforcing it. You can use the "Rule Insights" page to see if the contribution would have violated the rule. For more information, see "Managing rulesets for a repository."
Creating a branch or tag ruleset
-
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.
-
Alternatively, to create a ruleset targeting tags, click New tag 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."
Granting bypass permissions for your branch or tag ruleset
You can grant certain roles, teams, or apps bypass permissions as well as the ability to approve bypass requests for your ruleset. The following are eligible for bypass access:
- Repository admins, organization owners, and enterprise owners.
- The maintain or write role, or custom repository roles based on the write role
- Teams
- Deploy keys
- GitHub Apps
- Dependabot. For more information about Dependabot, see "Dependabot quickstart guide."
-
To grant bypass permissions for the ruleset, in the "Bypass list" section, click Add bypass.
-
In the "Add bypass" modal dialog that appears, search for the role, team, or app you would like to grant bypass permissions, then select the role, team, or app from the "Suggestions" section and click Add Selected.
-
Optionally, to grant bypass to an actor without allowing them to push directly to a repository, to the right of "Always allow," click , then click For pull requests only.
The selected actor is now required to open a pull request to make changes to a repository, creating a clear trail of their changes in the pull request and audit log. The actor can then choose to bypass any branch protections and merge that pull request.
Choosing which repositories to target in your organization
With your ruleset, you can choose to target all repositories in your organization, repositories in your organization that match a certain naming convention, repositories in your organization that have custom properties, or a list of manually selected repositories in your organization.
For more information about custom properties, see "Managing custom properties for repositories in your organization."
If a repository is targeted by a ruleset created at the organization level, only owners of the organization can edit the ruleset. However, people with admin access to the repository, or with a custom role including the "edit repository rules" permission, can create additional rulesets at the repository level. The rules in these rulesets will be aggregated with the rules defined at the organization level. The result is that creating a new ruleset can make the rules targeting a branch or tag more restrictive, but never less restrictive. For more information on creating rulesets, see "About rulesets."
Targeting all repositories in your organization
To target all repositories in your organization, in the "Target repositories" section, select Target: REPOSITORIES, then click All repositories.
Targeting repositories by naming convention in your organization
-
To target a dynamic list of repositories in your organization by naming convention, in the "Target repositories" section, select Target: REPOSITORIES, then click Dynamic list of repositories.
-
To begin defining a targeting pattern, in the "Targeting criteria" section, select Add a target , then click Include by pattern or Exclude by pattern.
-
In the modal dialog that appears, enter a repository naming pattern using
fnmatch
syntax, then click Add Inclusion pattern or Add Exclusion pattern. For more information onfnmatch
syntax, see "Usingfnmatch
syntax."Note: You can add multiple targeting criteria to the same ruleset. For example, you could include any repositories matching the pattern
*cat*
, then specifically exclude a repository matching the patternnot-a-cat
. -
Optionally, on the ruleset configuration page, select Prevent renaming of target repositories.
Targeting repositories by properties in your organization
You can target repositories in your organization by custom properties. For more information, see "Managing custom properties for repositories in your organization."
- To target a dynamic list of repositories in your organization by properties, in the "Target repositories" section, select Target: REPOSITORIES, then click Dynamic list by property.
- To add a target, in the "Targeting criteria" section, select Add a target , then click Include by property or Exclude by property.
- In the modal dialog that appears, select a custom or system property from the dropdown menu, then select a value for the property.
- Click Add target.
Targeting select repositories in your organization
- To target a static, manually selected list of repositories in your organization, in the "Target repositories" section, select Target: REPOSITORIES, then click Select repositories.
- To select repositories to target, in the "Targeting criteria" section, select Select repositories, then search for the name of each repository you would like to target. Select each repository from the search results.
Choosing which branches or tags to target
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
.
Selecting branch or tag protections
In the "Branch protections" or "Tag protections" section, select the rules you want to include in the ruleset. When you select a rule, you may be able to enter additional settings for the rule. For more information on the rules, see "Available rules for rulesets."
Notes: If you select Require status checks before merging, in the "Additional settings" section:
- You can enter the name of each status check you would like to require. To finish adding the status check as a requirement, you must click .
- If you select Require branches to be up to date before merging, you must define a check for the protection to take effect.
Adding metadata restrictions
Notes:
- Adding metadata restrictions can impact the experience of people contributing to your repository. Before you enact a ruleset with metadata restrictions, you can select the "Evaluate" enforcement status for your ruleset to test the effects of any metadata restrictions without impacting contributors. For more information on metadata restrictions, see "Available rules for rulesets."
- Metadata restrictions are intended to increase consistency between commits in your repository. They are not intended to replace security measures such as requiring code review via pull requests.
- If you squash merge a branch, all commits on that branch must meet any metadata requirements for the base branch.
-
Optionally, to add a rule to control commit metadata or branch names, in the "Restrictions" section, click Restrict commit metadata or Restrict branch names.
-
Configure the settings for the restriction, then click Add. You can add multiple restrictions to the same ruleset.
-
To match a given regex pattern, in the "Requirement" dropdown, select Must match a given regex pattern.
For most requirements, such as "Must start with a matching pattern," the pattern you enter is interpreted literally, and wildcards are not supported. For example, the
*
character only represents the literal*
character.For more complex patterns, you can select "Must match a given regex pattern" or "Must not match a given regex pattern," then use regular expression syntax to define the matching pattern. For more information, see "About regular expressions for commit metadata."
Anyone who views the rulesets for a repository will be able to see the description you provide.
Finalizing your branch or tag ruleset and next steps
To finish creating your ruleset, click Create. If the enforcement status of the ruleset is set to "Active", the ruleset takes effect immediately.
You can view insights for the ruleset to see how the rules are affecting your contributors. If the enforcement status is set to "Evaluate", you can see which actions would have passed or failed if the ruleset was active. For more information on insights for rulesets, see "Managing rulesets for a repository."
Creating a push ruleset
Note
This ruleset will enforce push restrictions for this repository's entire fork network.
You can create a push ruleset for private or internal repositories in your 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 push 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."
Granting bypass permissions for your push ruleset
Note
Bypass permissions for push rulesets that target a repository will be inherited by the entire fork network for this repository. This means that the only users who can bypass this ruleset for any repository in this repository's entire fork network are the users who can bypass this ruleset in the root repository.
You can grant certain roles, teams, or apps bypass permissions as well as the ability to approve bypass requests for your ruleset. The following are eligible for bypass access:
- Repository admins, organization owners, and enterprise owners.
- The maintain or write role, or custom repository roles based on the write role
- Teams
- Deploy keys
- GitHub Apps
- Dependabot. For more information about Dependabot, see "Dependabot quickstart guide."
- To grant bypass permissions for the ruleset, in the "Bypass list" section, click Add bypass.
- In the "Add bypass" modal dialog that appears, search for the role, team, or app you would like to grant bypass permissions, then select the role, team, or app from the "Suggestions" section and click Add Selected.
Choosing which repositories to target in your organization
With your ruleset, you can choose to target all repositories in your organization, repositories in your organization that match a certain naming convention, repositories in your organization that have custom properties, or a list of manually selected repositories in your organization.
For more information about custom properties, see "Managing custom properties for repositories in your organization."
If a repository is targeted by a ruleset created at the organization level, only owners of the organization can edit the ruleset. However, people with admin access to the repository, or with a custom role including the "edit repository rules" permission, can create additional rulesets at the repository level. The rules in these rulesets will be aggregated with the rules defined at the organization level. The result is that creating a new ruleset can make the rules targeting a branch or tag more restrictive, but never less restrictive. For more information on creating rulesets, see "About rulesets."
Targeting all repositories in your organization
To target all repositories in your organization, in the "Target repositories" section, select Target: REPOSITORIES, then click All repositories.
Targeting repositories by naming convention in your organization
-
To target a dynamic list of repositories in your organization by naming convention, in the "Target repositories" section, select Target: REPOSITORIES, then click Dynamic list of repositories.
-
To begin defining a targeting pattern, in the "Targeting criteria" section, select Add a target , then click Include by pattern or Exclude by pattern.
-
In the modal dialog that appears, enter a repository naming pattern using
fnmatch
syntax, then click Add Inclusion pattern or Add Exclusion pattern. For more information onfnmatch
syntax, see "Usingfnmatch
syntax."Note: You can add multiple targeting criteria to the same ruleset. For example, you could include any repositories matching the pattern
*cat*
, then specifically exclude a repository matching the patternnot-a-cat
. -
Optionally, on the ruleset configuration page, select Prevent renaming of target repositories.
Targeting repositories by properties in your organization
You can target repositories in your organization by custom properties. For more information, see "Managing custom properties for repositories in your organization."
- To target a dynamic list of repositories in your organization by properties, in the "Target repositories" section, select Target: REPOSITORIES, then click Dynamic list by property.
- To add a target, in the "Targeting criteria" section, select Add a target , then click Include by property or Exclude by property.
- In the modal dialog that appears, select a custom or system property from the dropdown menu, then select a value for the property.
- Click Add target.
Targeting select repositories in your organization
- To target a static, manually selected list of repositories in your organization, in the "Target repositories" section, select Target: REPOSITORIES, then click Select repositories.
- To select repositories to target, in the "Targeting criteria" section, select Select repositories, then search for the name of each repository you would like to target. Select each repository from the search results.
Selecting push protections
You can block pushes to this repository and this repository's entire fork network based on file extensions, file path lengths, file and folder paths, and file sizes.
Any push protections you configure will block pushes in this repository and throughout this repository's entire fork network.
-
Under "Push protections," click the restrictions you want to apply. Then fill in the details for the restrictions you select.
For file path restrictions, you can use partial or full paths. You can use
fnmatch
syntax for this. For example, a restriction targetingtest/demo/**/*
prevents any pushes to files or folders in thetest/demo/
directory. A restriction targetingtest/docs/pushrules.md
prevents pushes specifically to thepushrules.md
file in thetest/docs/
directory. For more information, see "Creating rulesets for a repository."
Finalizing your push ruleset and next steps
To finish creating your ruleset, click Create. If the enforcement status of the ruleset is set to "Active", the ruleset takes effect immediately.
You can view insights for the ruleset to see how the rules are affecting your contributors. If the enforcement status is set to "Evaluate", you can see which actions would have passed or failed if the ruleset was active. For more information on insights for rulesets, see "Managing rulesets for a repository."