diff --git a/INSTALL.md b/INSTALL.md index 84f5720..51150c4 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -118,6 +118,24 @@ PR comment (approval required): --- +## ⚠️ CRITICAL: GitHub Rulesets & Strict Mode + +If you use **GitHub Repository Rulesets** (recommended) to enforce this check, follow these rules to avoid merge loops: + +1. **Create TWO rulesets** instead of one. +2. **Ruleset 1: "Permission Protocol"** + - Required status check: `Permission Protocol` + - **Strict mode: OFF** (`strict_required_status_checks_policy: false`) + - *Why?* Authorization doesn't go stale when `main` advances. Strict mode creates phantom "Expected" errors that block merges unnecessarily. +3. **Ruleset 2: "Build Protection"** + - Required status check: `Build and test` (or your CI check) + - **Strict mode: ON** (`strict_required_status_checks_policy: true`) + - *Why?* This ensures your code actually compiles with the latest `main` before merging. + +**Result:** Your code stays fresh, but your human approvals don't get wiped out every time someone else merges to `main`. + +--- + ## Common Errors ### 401 Unauthorized diff --git a/README.md b/README.md index d27678e..6f3c015 100644 --- a/README.md +++ b/README.md @@ -149,6 +149,17 @@ Open any PR to the protected branch. Deploy Gate always creates/verifies a reque --- +## ⚠️ Recommended: GitHub Ruleset Pattern + +To avoid "merge loops" where approvals go stale when `main` advances, we recommend a **two-ruleset pattern** if you use GitHub Repository Rulesets: + +1. **Ruleset 1 (Permission Protocol):** Require `Permission Protocol` status check with **Strict mode: OFF**. +2. **Ruleset 2 (Build Protection):** Require your build/test checks with **Strict mode: ON**. + +This ensures your code is up-to-date with `main`, but your human approvals stick once granted. [See full guide →](./INSTALL.md#%EF%B8%8F-critical-github-rulesets--strict-mode) + +--- + ## Configuration | Input | Description | Default |