From 0cb69dc22e53f5f773677b1e60d7bc144b174318 Mon Sep 17 00:00:00 2001
From: Matt Travi <programmer@travi.org>
Date: Fri, 30 Aug 2024 15:37:16 -0500
Subject: [PATCH] docs(rulesets): first iteration of shape of ruleset
 definition

for #732
---
 docs/plugins/rulesets.md | 53 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/plugins/rulesets.md

diff --git a/docs/plugins/rulesets.md b/docs/plugins/rulesets.md
new file mode 100644
index 000000000..26b459581
--- /dev/null
+++ b/docs/plugins/rulesets.md
@@ -0,0 +1,53 @@
+# Repository Rulesets
+
+See https://docs.github.com/en/rest/repos/rules#update-a-repository-ruleset for
+all available ruleset properties and a description of each.
+
+```yaml
+rulesets:
+  - name: prevent destruction of the default branch
+    target: branch
+    enforcement: active
+    conditions:
+      ref_name:
+        include:
+          - "~DEFAULT_BRANCH"
+    rules:
+      - type: deletion
+      - type: non_fast_forward
+
+  - name: verification must pass
+    target: branch
+    enforcement: active
+    conditions:
+      ref_name:
+        include:
+          - "~DEFAULT_BRANCH"
+    rules:
+      - type: required_status_checks
+        parameters:
+          required_status_checks:
+            - context: test
+              integration_id: 123456
+    bypass_actors:
+      - actor_id: 5
+        actor_type: RepositoryRole
+        bypass_mode: pull_request
+
+  - name: changes must be reviewed
+    target: branch
+    enforcement: active
+    conditions:
+      ref_name:
+        include:
+          - "~DEFAULT_BRANCH"
+    rules:
+      - type: pull_request
+        parameters:
+          required_approving_review_count: 1
+          require_code_owner_review: true
+    bypass_actors:
+      - actor_id: 654321
+        actor_type: Integration
+        bypass_mode: always
+```