[2026-08-11] Convert a repository's Branch Protections to Rulesets [GA] (#62505)

Co-authored-by: mchammer01 <42146119+mchammer01@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Laura Coursen <lecoursen@github.com>
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>
Copilot-Session: a74cf076-1dbb-4bb0-86f7-126936c979c9
Copilot-Session: 716e1b10-ce90-4d4a-b506-551c01bc5b54

Author: 6 people

content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md

@@ -41,7 +41,7 @@ By default, the restrictions of a branch protection rule don't apply to people w
 {% data reusables.pull_requests.you-can-auto-merge %}
 
 > [!NOTE]
-> Only a single branch protection rule can apply at a time, which means it can be difficult to know which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets).
+> Only a single branch protection rule can apply at a time, which means it can be difficult to know which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}This restriction does not apply to rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). {% data reusables.repositories.rulesets-convert-branch-protection-rule %}
 
 ## About branch protection settings
 

content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md

@@ -43,7 +43,7 @@ To create an exception to an existing branch rule, you can create a new branch p
 For more information about each of the available branch protection settings, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches).
 
 > [!NOTE]
-> Only a single branch protection rule can apply at a time, which means it can be difficult to know how which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets).
+> Only a single branch protection rule can apply at a time, which means it can be difficult to know how which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). {% data reusables.repositories.rulesets-convert-branch-protection-rule %}
 
 ## Creating a branch protection rule
 

content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets.md

@@ -44,14 +44,16 @@ For each ruleset you create, you specify which branches or tags in your reposito
 
 ## About rulesets and protected branches
 
-Rulesets work alongside any branch protection rules in a repository. Many of the rules you can define in rulesets are similar to protection rules, and you can start using rulesets without overriding any of your existing protection rules.
+Rulesets and branch protection rules can both protect branches in a repository. They work alongside each other, and all applicable rules are enforced. For more information, see [About rule layering](#about-rule-layering).
 
-Rulesets have the following advantages over branch protection rules.
+Rulesets offer more flexible ways to manage and understand protections:
 
-* Unlike protection rules, multiple rulesets can apply at the same time, so you can be confident that every rule targeting a branch in your repository will be evaluated when someone interacts with that branch. See [About rule layering](#about-rule-layering).
-* Rulesets have statuses, so you can easily manage which rulesets are active in a repository without needing to delete rulesets.
-* Anyone with read access to a repository can view the active rulesets for the repository. This means a developer can understand why they have hit a rule, or an auditor can check the security constraints for the repository, without requiring admin access to the repository.
-* You can create additional rules to control the metadata of commits entering a repository, such as the commit message and the author's email address. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets){% ifversion ghec %}."{% else %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %}
+* Multiple rulesets can apply to the same branch at the same time, while only one branch protection rule applies.
+* You can change a ruleset's enforcement status without deleting the ruleset.
+* Anyone with read access to a repository can view its active rulesets. This helps developers understand which rules apply and allows auditors to review protections without administrator access.
+* Rulesets can also control commit metadata, such as commit messages and author email addresses. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets){% ifversion ghec %}."{% else %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %}
+
+{% data reusables.repositories.rulesets-convert-branch-protection-rule %}
 
 ## Using ruleset enforcement statuses
 

content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/converting-branch-protections-to-rulesets.md

@@ -0,0 +1,66 @@
+---
+title: Converting branch protections to rulesets
+intro: 'Use rulesets to gain clearer visibility and control over your repository protections while preserving their existing behavior.'
+product: '{% data reusables.gated-features.repo-rules %}'
+versions:
+  feature: branch-protection-ruleset-conversion
+permissions: 'People with admin access to a repository, or a custom role with the "edit repository rules" permission, can create, edit, and delete rulesets for a repository.'
+shortTitle: Convert to rulesets
+category:
+  - Manage branches and protect code
+---
+
+## About converting branch protections to rulesets
+
+Rulesets give you clearer visibility and control over how protections apply to a repository. Unlike branch protection rules, multiple rulesets can apply to the same branch at the same time, and people with read access can view the active rulesets. This helps developers understand the rules that affect them and lets auditors review repository protections without administrator access.
+
+To move your existing protections to this model, convert one branch protection rule at a time in a guided flow. {% data variables.product.github %} generates one or more rulesets that preserve the original rule's behavior. You can preview the rulesets{% ifversion repo-rules-enterprise %}, choose how each one is enforced,{% endif %} and verify the result before you remove the original branch protection rule.
+
+For more information about rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets).
+
+## Converting a branch protection rule to a ruleset
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+{% data reusables.repositories.repository-branches %}
+1. Under "Branch protection rules", find the rule you want to convert, then click **Convert to ruleset**.
+1. Set the ruleset name for each ruleset that will be created in this conversion.
+1. Review the "New behavior" section to understand what will change when you create the ruleset or rulesets.{% ifversion repo-rules-enterprise %}
+1. Under "Enforcement status", choose how the new ruleset is enforced. For more information, see [Choosing an enforcement status](#choosing-an-enforcement-status).{% endif %}
+1. {% ifversion repo-rules-enterprise %}If you chose **Active**, you can optionally remove the original branch protection rule as part of the conversion by selecting **Delete branch protection rule once migration is done**.{% else %}Optionally, to remove the original branch protection rule as part of the conversion, select **Delete branch protection rule once migration is done**.{% endif %}
+1. Click **Create ruleset**. If the conversion produces more than one ruleset, the button includes the number of rulesets, for example, **Create 2 rulesets**.
+
+If you keep the original branch protection rule, it continues to protect matching branches. An **Active** ruleset is enforced alongside it, so changes must satisfy both.{% ifversion repo-rules-enterprise %} An **Evaluate** ruleset records how it would behave without enforcing its rules.{% endif %}
+
+> [!NOTE]
+> The conversion covers all branch protection types with the exception of the "Require conversation resolution before merging" setting. In branch protections, this setting exists on its own. In rulesets, conversation resolution is part of the pull request rule and only applies when that rule is enabled. As a result, this setting does not map one to one during conversion. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets).
+
+{% ifversion repo-rules-enterprise %}
+
+### Choosing an enforcement status
+
+When you convert a branch protection rule, you choose an enforcement status for the new ruleset.
+
+* **Active**: the ruleset is enforced as soon as it is created.
+* **Evaluate**: the ruleset runs without enforcing its rules, so you can review how it would behave before it takes effect.
+
+Although **Active** is selected by default, consider which status fits your situation:
+
+* If you have created or migrated similar rules before and are confident in the outcome, you can use **Active**.
+* If this is your first migration, consider starting in **Evaluate** mode. You can confirm that the new ruleset behaves as expected, then delete the original branch protection rule once you have finished testing.
+
+{% else %}
+
+The new ruleset has an **Active** status, which means that it is enforced as soon as it is created.
+
+{% endif %}
+
+### Deleting the original branch protection rule
+
+After you convert a rule, return to the **Branches** settings page. If you did not opt to delete the branch protection rule during the conversion process and the new ruleset fully covers it, the listed rule displays the message "This rule is fully covered by rulesets and can be safely deleted", and a **Delete** button appears in place of the **Convert to ruleset** button.
+
+Before you delete the original rule, we recommend confirming that the new ruleset behaves as you expect{% ifversion repo-rules-enterprise %}, especially if you created it in **Evaluate** mode{% endif %}. When you are ready, click **Delete** to remove the branch protection rule.
+
+## Further reading
+
+* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)

content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/index.md

@@ -8,6 +8,7 @@ children:
   - /about-rulesets
   - /creating-rulesets-for-a-repository
   - /managing-rulesets-for-a-repository
+  - /converting-branch-protections-to-rulesets
   - /available-rules-for-rulesets
   - /troubleshooting-rules
 shortTitle: Manage rulesets

data/features/branch-protection-ruleset-conversion.yml

@@ -0,0 +1,6 @@
+# Reference: docs-content#23257
+# Convert a repository's branch protections to rulesets
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.23'

data/reusables/repositories/rulesets-convert-branch-protection-rule.md

@@ -0,0 +1 @@
+{% ifversion branch-protection-ruleset-conversion %}To convert an existing branch protection rule to rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/converting-branch-protections-to-rulesets).{% endif %}