Document allowed exceptions for push rules (#62873)

Co-authored-by: Copilot App <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: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pararohan <452580+pararohan@users.noreply.github.com>
Copilot-Session: 268c80e7-020f-43b5-a13f-d6010afd5f0c

Author: 5 people

content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md

@@ -319,6 +319,14 @@ Prevent commits that include changes in specified file paths from being pushed t
 
 {% data reusables.repositories.rulesets-push-rules-path-example %}
 
+{% ifversion push-rule-allowed-exceptions %}
+
+You can also add allowed exceptions to this rule. A file matching an allowed exception can be pushed even when it also matches a restricted path.
+
+{% data reusables.repositories.rulesets-push-rules-allowed-exceptions %}
+
+{% endif %}
+
 ## Restrict file path length
 
 Prevent commits that include file paths that exceed a specified character limit from being pushed to the repository.
@@ -327,6 +335,20 @@ Prevent commits that include file paths that exceed a specified character limit
 
 Prevent commits that include files with specified file extensions from being pushed to the repository. {% ifversion available-rules-limit %}Limit is 200 entries and up to 200 characters in each entry.{% endif %}
 
+{% ifversion push-rule-allowed-exceptions %}
+
+If you need to allow an exception for a single file of an otherwise blocked file type, use "Restrict file paths" with a pattern such as `**/*.jar`. Only the "Restrict file paths" and "Restrict file size" rules support allowed exceptions.
+
+{% endif %}
+
 ## Restrict file size
 
 Prevent commits that exceed a specified file size limit from being pushed to the repository.
+
+{% ifversion push-rule-allowed-exceptions %}
+
+You can also add allowed exceptions to this rule. A file matching an allowed exception can exceed the file size limit.
+
+{% data reusables.repositories.rulesets-push-rules-allowed-exceptions %}
+
+{% endif %}

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

@@ -21,6 +21,12 @@ If a branch or tag is targeted by rules restricting the metadata of commits, you
 
 When utilizing push rulesets, a maximum of 1000 reference updates are allowed per push. If your push exceeds this limit, it will be rejected. For more information see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#creating-a-push-ruleset).
 
+{% ifversion push-rule-allowed-exceptions %}
+
+If your push is blocked by a rule restricting file paths or file size, check whether the ruleset defines allowed exceptions. A repository, organization, or enterprise administrator can add an allowed exception for a file that must remain pushable. See [Restrict file paths](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#restrict-file-paths) and [Restrict file size](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#restrict-file-size).
+
+{% endif %}
+
 Additionally, push rulesets apply to the "Create a blob", "Create a tree", and "Create or update file contents" endpoints in the REST API. See [AUTOTITLE](/rest/git/blobs?apiVersion=2022-11-28#create-a-blob), [AUTOTITLE](/rest/git/trees?apiVersion=2022-11-28#create-a-tree), and [AUTOTITLE](/rest/repos/contents?apiVersion=2022-11-28#create-or-update-file-contents).
 
 ## Troubleshooting required status checks

data/features/push-rule-allowed-exceptions.yml

@@ -0,0 +1,7 @@
+# Reference: github/releases#9966
+# "Allowed exceptions" (ignored_file_paths) for the Restrict file paths
+# and Restrict file size push rules.
+# GHES availability TBC — add a ghes key once confirmed.
+versions:
+  fpt: '*'
+  ghec: '*'

data/reusables/repositories/push-rulesets-overview.md

@@ -7,9 +7,11 @@ Push rulesets allow you to:
 * **Restrict file paths:** Prevent commits that include changes in specified file paths from being pushed.
 
   {% data reusables.repositories.rulesets-push-rules-path-example %}
+  
+  {% ifversion push-rule-allowed-exceptions %}You can add allowed exceptions for paths that should remain pushable.{% endif %}
 * **Restrict file path length:** Prevent commits that include file paths that exceed a specified character limit from being pushed.
 * **Restrict file extensions:** Prevent commits that include files with specified file extensions from being pushed.
-* **Restrict file size:** Prevent commits that exceed a specified file size limit from being pushed.
+* **Restrict file size:** Prevent commits that exceed a specified file size limit from being pushed.{% ifversion push-rule-allowed-exceptions %} You can add allowed exceptions for files that may exceed the limit.{% endif %}
 
 ### About push rulesets for forked repositories
 

data/reusables/repositories/rulesets-push-rules-allowed-exceptions.md

@@ -0,0 +1 @@
+Allowed exceptions use `fnmatch` syntax and are validated when you save the ruleset. For example, `**/gradle/wrapper/*.jar` allows the Gradle wrapper JAR file in any directory.

data/reusables/repositories/rulesets-push-rules-step.md

@@ -5,3 +5,8 @@ Any push protections you configure will block pushes in this repository and thro
 1. 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. {% data reusables.repositories.rulesets-push-rules-path-example %}
+{%- ifversion push-rule-allowed-exceptions %}
+1. Optionally, for the "Restrict file paths" and "Restrict file size" restrictions, under "Allowed exceptions," add the file paths you want to exempt from the restriction.
+
+   {% data reusables.repositories.rulesets-push-rules-allowed-exceptions %}
+{%- endif %}