Managing rulesets for repositories in your organization

About managing rulesets for an organization

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.

When you create a ruleset for an organization, you use fnmatch syntax to define which repositories in your organization, and which branches or tags in those repositories, are targeted by the ruleset. For more information, see "Using fnmatch syntax." This provides a quicker way for managing rulesets than creating a separate ruleset for each repository you want to target.

When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. This can be users with a certain role, such as repository administrator, or it can be specific teams or GitHub Apps.

You can use the REST API to manage rulesets. For more information, see "Rules."

If a repository is targeted by a ruleset created at organization level, only owners of the organization can edit this 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 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, see "About rulesets."

You may be prompted to confirm access to your account before you can create, edit, or delete a ruleset. For more information, see "Sudo mode."

Forks do not inherit rulesets from their upstream repositories. However, forks owned by your organization are subject to the rulesets you create, like any other repository.

Creating a ruleset

1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations.

   

2. Next to the organization, click Settings.

3. In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Repository rulesets.

   

4. You can create a ruleset targeting branches, or a ruleset targeting tags.

   • To create a ruleset targeting branches, click New branch ruleset.

   • To create a ruleset targeting tags, select , then click New tag ruleset.

     

5. In the "General" section:

   • Type a name for the ruleset.
   • Select the enforcement status. You must set the status to Active if you want the ruleset to be enforced. Alternatively, if you set the status to Evaluate, the 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. For more information, see "Viewing insights for rulesets."
   • If you want repository or organization owners to be able to bypass the rules in the ruleset, change the selection in the dropdown menu under "Bypass mode."

6. Optionally, in the "Bypass list" section, add teams or GitHub Apps to give them bypass permission for the ruleset.

   Note: The bypass list is independent of the bypass mode. The teams and apps you add will be able to bypass the ruleset even if you set "Bypass mode" to "Not permitted."

7. In the "Target repositories" section, select Add a target to add repositories. You can include all repositories in your organization, or you can use fnmatch syntax to include or exclude repository names 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 any repositories matching the pattern *cat*, then specifically exclude a repository matching the pattern not-a-cat.

   Optionally, to prevent users from renaming any of the targeted repositories, select Prevent renaming of target repositories.

8. 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.

9. 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."

10. Optionally, in the "Metadata restrictions" section, to add a rule to control the metadata of commits being pushed to the branch or tag, click .

    

    Note: Adding metadata restrictions can impact the experience of people contributing to your repository. Before you add metadata restrictions to a ruleset, make sure you understand their potential consequences. For more information, see "Available rules for rulesets."

11. If you're adding a metadata restriction, configure the settings for the metadata restriction rule, then click Add. You can add multiple restrictions to the same ruleset.

    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 "Using regular expressions for commit metadata."

    Anyone who views the rulesets for a repository will be able to see the description you provide.

12. To create the ruleset, click Create.

Editing a ruleset

You can edit a ruleset to change parts of the ruleset, such as the name, bypass permissions, or rules. You can also edit a ruleset to change its status, such as if you want to enable or temporarily disable a ruleset.

1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations.

   

2. Next to the organization, click Settings.

3. In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Repository rulesets.

   

4. On the "Rulesets" page, click the name of the ruleset you want to edit.

5. Change the ruleset as required. For information on the available rules, see "Available rules for rulesets."

6. At the bottom of the page, click Save changes.

Deleting a ruleset

1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations.

   

2. Next to the organization, click Settings.

3. In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Repository rulesets.

   

4. Click the name of the ruleset you want to delete.

5. To the right of the ruleset's name, select , then click Delete ruleset.

   

Viewing insights for rulesets

You can view insights for rulesets to see how rulesets are affecting the repositories in your organization. On the "Rule Insights" page, you will see a timeline of the following user actions. You can use filters to find what you're looking for.

• Actions that have been checked against one or more rulesets and passed.
• Actions that have been checked against one or more rulesets and failed.
• Actions where someone has bypassed one or more rulesets.

If a ruleset is running in "Evaluate" mode, you can see actions that would have passed or failed if the ruleset had been active.

1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations.

   

2. Next to the organization, click Settings.

3. In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Repository rule insights.

   

4. On the "Rule Insights" page, use the dropdown menus at the top of the page to filter the actions by ruleset, repository, actor, and time period.

5. To see which specific rules failed or required a bypass, click , then expand the name of the ruleset.

   

Using fnmatch syntax

You can use fnmatch syntax to define patterns to target the names of branches, tags, and repositories 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.

Using regular expressions for commit metadata

When you add metadata restrictions, 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.

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.

Regular expressions consider multiple lines of text by default. For example, if you have a multiline commit message, the pattern ^ABC will be a match if any line in the message starts with ABC. To match the start of the message specifically, you can start your expression with \A.

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.

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-_]$

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-]+)*))?$

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}$

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]+$

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]*)

Matches: feat: allow provided config object to extend other configs

Does not match: Add conditional logic to foo.bar