@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/cicd/mergify/assets/templates/mergify.yml

@@ -0,0 +1,215 @@
+# Mergify configuration template.
+#
+# Copy to the repository root as `.mergify.yml`, then replace every <PLACEHOLDER>
+# and work through the TODOs. Validate before committing:
+#
+#     mergify config validate
+#     mergify config simulate https://github.com/<owner>/<repo>/pull/<n>
+#
+# Shape of this template:
+#   - enqueue is HYBRID: AUTO on ready + review-PASS, MANUAL (`@mergifyio queue`) otherwise
+#   - batch mode, batch_size 3
+#   - update_method: rebase (head-freshness intent; see the note on it below)
+#   - one CI gate (`gate`), defined once and asserted in three places
+#   - queue-only merges, with the admin escape hatch routed THROUGH Mergify
+#
+# Queue-only merges are half configured here and half in ruleset.json:
+# its `update` rule makes Mergify the only actor that may write to the branch,
+# so the admin escape hatch cannot be "merge it by hand" — it has to be
+# something Mergify performs. That is the `pull_request_rules` block at the end.
+
+shared:
+  # ---------------------------------------------------------------------------
+  # THE GATE. Define the CI requirement once and reference it by anchor in the
+  # queue-entry gate, the queue-merge gate and the merge protection.
+  #
+  # TODO: replace `gate` if your roll-up job has another name. It must be the
+  # always-reporting roll-up job (`if: always()`, no workflow `paths:` filter;
+  # github-actions skill, conditional-ci.md). A path-filtered workflow leaves the
+  # check ABSENT on some PRs and they sit in the queue forever: fix the workflow.
+  # Only if you cannot, wrap the condition in an `or` with a `-files ~=` exemption
+  # that also lists the workflow file itself (references/traps.md).
+  gate: &gate check-success = gate
+
+queue_rules:
+  - name: default
+    # No checks timeout: a run slowed by busy runners waits instead of
+    # dequeuing (and bisecting) green PRs. Fix slow CI, do not cap it.
+    checks_timeout: null
+    # Where GitHub branch-protection / ruleset requirements get injected.
+    #   queue (default) — injected into BOTH queue-entry and merge conditions
+    #   merge           — injected only while merging
+    #
+    # Use `merge` when a Mergify-published check is itself REQUIRED by the
+    # ruleset: that check deliberately fails before the PR is in the queue, and
+    # with the default `queue` mode it would block the very enqueue step that
+    # makes it pass.
+    branch_protection_injection_mode: merge
+
+    # ---- Step 1: what a PR must satisfy to ENTER the queue --------------------
+    # `-draft` is deliberately ABSENT here, and from merge_conditions below.
+    # Auto-enqueue already skips drafts (`-draft` in auto_merge_conditions), and a
+    # draft condition here shows up as a lone unmet condition on a PR nobody
+    # expected to be held. Do not add it back without reading the next paragraph.
+    #
+    # What the absence costs, stated plainly so it is a choice and not a surprise:
+    # GitHub cannot merge a draft pull request. A draft that gets enqueued anyway
+    # is admitted, rides a full batch CI run, reaches the front and fails at the
+    # merge call — taking the batch's innocent PRs through that failure with it.
+    # Marking a queued PR as draft also no longer pulls it out of the queue;
+    # use `@mergifyio dequeue` for that.
+    queue_conditions:
+      - base = <main-branch>
+      - *gate
+
+    # ---- Step 2: what must hold to MERGE from the front of the queue ----------
+    # Not redundant with step 1: Mergify tests the batch merged WITH its base
+    # here — a tree that existed when no individual PR's CI ran.
+    # Add a second, queue-only check here only for work too slow for every PR
+    # push; never one that repeats the PR's own `gate` job.
+    merge_conditions:
+      - *gate
+
+    # ---- BATCH MODE ----------------------------------------------------------
+    # Test up to 3 PRs as one CI run — this skill's default. The key must be
+    # explicit: unset, `batch_size` silently runs at Mergify's built-in default of
+    # 1 (no batching), so this line is what turns batching on. Mergify groups a batch by
+    # relationship (stacks together, then similar scopes/directories), not raw
+    # queue order. A red batch is bisected by Mergify, so innocent PRs are not
+    # discarded; only the culprit is dequeued.
+    #
+    # REQUIRED GitHub setting: "Require branches to be up to date before merging"
+    # must be DISABLED on the protected branch. Batches cannot merge with it on.
+    batch_size: 3
+
+    # How long to hold the gate open for a batch to fill. This is a straight
+    # latency tax on a LONE PR — Mergify waits the full window before giving up
+    # on company. Keep it short where PRs usually arrive one at a time.
+    batch_max_wait_time: 10 seconds
+
+    # Bound on how many times a failing batch may be split to isolate the
+    # culprit. Each split is another CI run. With batch_size 3 a single bad PR
+    # is normally found in ~2 splits; this only caps the pathological case.
+    batch_max_failure_resolution_attempts: 10
+
+    # ---- HEAD FRESHNESS ------------------------------------------------------
+    # `update_method` applies ONLY to in-place checks, and in-place checks are
+    # enabled only when max_parallel_checks == 1 AND every queue has
+    # batch_size == 1 AND every queue CI is single-step (no extra
+    # merge_conditions). With batch_size 3 it is therefore inert today: head
+    # freshness comes from the queue branch, which Mergify builds as
+    # base + batch and runs CI against.
+    #
+    # It is kept here deliberately so that dropping to batch_size 1 does not
+    # silently change update behaviour. To rebase the PR BRANCH ITSELF while
+    # batching, use the `update`/`rebase` action or `@mergifyio update`
+    # (see the skill's "Enforce head" section) — not this option.
+    update_method: rebase
+
+    # Keep the PR's commits (configuration.md, "Stack-ready"): a PR built on another lands cleanly.
+    merge_method: merge-batch
+
+merge_queue:
+  # Parallel speculative checks. Batch splits are tested in parallel during
+  # bisection, so a red batch resolves in roughly log time. There is nothing to
+  # gain from more parallel checks than a batch can split into.
+  max_parallel_checks: 3
+
+merge_protections_settings:
+  # check-runs is what a GitHub branch ruleset can mark REQUIRED.
+  reporting_method: check-runs
+  post_comment: true
+
+  # ENQUEUE: AUTO on ready + review-PASS, MANUAL otherwise. A PR auto-queues the
+  # moment it is `-draft` (ready), has >=1 approval with no open change request,
+  # and the CI gate is green; short of that it waits for a human `@mergifyio queue`.
+  # The manual hatch always works — `@mergifyio queue` ignores these conditions,
+  # and `merge_conditions` gate on CI only — so a hand-queued PR merges on green
+  # without a review. `-draft` lives HERE, not in queue_conditions/merge_conditions
+  # (see the `-draft` note below).
+  #
+  # Do NOT use the deprecated `auto_merge: true` or `queue_rules[].autoqueue`.
+  # For fully MANUAL enqueue instead, delete this block and say so in a comment
+  # (an omitted key reads as an oversight and someone will "fix" it back).
+  auto_merge_conditions:
+    - "-draft"
+    - "#approved-reviews-by >= 1"
+    - "#changes-requested-reviews-by = 0"
+    - *gate
+
+merge_protections:
+  # Republish the gate as a Mergify check-run so a GitHub ruleset has one stable
+  # check name to require.
+  #
+  # NEVER write `success_conditions: [queue-name = default]` here to "force all
+  # merges through the queue". Merge-protection conditions are injected into the
+  # queue's ENTRY conditions, while the ruleset requires the resulting check
+  # BEFORE entry — entry then waits on a check that cannot go green until after
+  # entry, and the repository deadlocks. `branch_protection_injection_mode:
+  # merge` does not prevent this; it governs GitHub-side injection, not
+  # Mergify's own merge_protections. Queue-only merges are enforced by the
+  # GitHub ruleset's `update` rule instead — see ruleset.json.
+  - name: gate before merge
+    description: >-
+      The CI gate, asserted as a required merge protection, so a ruleset
+      has one stable Mergify check name to require.
+    if:
+      - base = <main-branch>
+    success_conditions:
+      - *gate
+
+# ---------------------------------------------------------------------------
+# ADMIN ESCAPE HATCHES — both routed through Mergify.
+#
+# With the `update` rule in ruleset.json, Mergify is the only actor allowed to
+# write to the protected branch. So "an admin merges it by hand" is no longer
+# possible, and the escape hatch has to be an action Mergify takes. There are
+# two, and they are NOT interchangeable.
+# ---------------------------------------------------------------------------
+
+# ESCAPE HATCH 1 (preferred): jump the line, keep the tests.
+# The PR still enters the queue and still has to pass CI — it just stops waiting
+# behind everything else. This covers the overwhelming majority of "this is
+# urgent" cases and costs nothing in safety, so reach for it first.
+priority_rules:
+  - name: urgent — front of the queue
+    conditions:
+      - label = urgent
+    priority: high
+
+# ESCAPE HATCH 2 (break glass): skip the queue entirely.
+# Merges immediately, WITHOUT the queue and WITHOUT the batch's CI run. This is
+# the lever that can put a broken commit on the protected branch, so treat the
+# label as the audited artifact: Mergify records the merge, and GitHub records
+# who applied the label.
+#
+# GitHub cannot restrict who applies a label, and Mergify's `sender-permission`
+# attribute only works for COMMANDS (`@mergifyio …`), not label events — so this
+# rule cannot be technically limited to admins. It is a convention backed by an
+# audit trail, not an enforced permission. If that is not good enough for you,
+# delete this rule and let a genuine emergency go through the OrganizationAdmin
+# bypass in ruleset.json instead, which GitHub does enforce and does audit.
+#
+# TODO: delete this whole rule if you would rather have no queue-skip at all.
+pull_request_rules:
+  - name: emergency merge — skips the queue, use only when the queue cannot run
+    conditions:
+      - base = <main-branch>
+      - label = emergency-merge
+      - -draft
+    actions:
+      merge:
+        method: merge
+      comment:
+        message: >-
+          Merged via the `emergency-merge` label — this bypassed the merge queue
+          and its CI run. Please confirm the branch is healthy.
+
+# Who may enqueue. Defaults are `sender-permission >= write` for `queue` and
+# `dequeue`; tighten to `admin` if enqueueing should itself be a privileged act.
+#
+# TODO: delete this block to keep the defaults.
+commands_restrictions:
+  queue:
+    conditions:
+      - sender-permission >= write

package/skills/cicd/mergify/assets/templates/ruleset.json

@@ -0,0 +1,46 @@
+{
+  "name": "default",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["~DEFAULT_BRANCH"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    {
+      "type": "update",
+      "parameters": {
+        "update_allows_fetch_and_merge": true
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          {
+            "context": "Mergify Merge Protections",
+            "integration_id": 10562
+          }
+        ]
+      }
+    }
+  ],
+  "bypass_actors": [
+    {
+      "actor_id": 10562,
+      "actor_type": "Integration",
+      "bypass_mode": "exempt"
+    },
+    {
+      "actor_id": 1,
+      "actor_type": "OrganizationAdmin",
+      "bypass_mode": "always"
+    }
+  ]
+}

package/skills/cicd/mergify/references/branch-protection.md

@@ -0,0 +1,282 @@
+# Branch Protection: the GitHub ruleset
+
+Everything GitHub-side that makes the Mergify queue binding. Read this when
+**setting up or changing branch protection** — not needed to debug a stuck PR.
+
+Contents:
+
+- [Who enforces what](#who-enforces-what) — the bypass-scope problem, and
+  what GitHub enforces vs what Mergify enforces
+- [What the rules do](#what-the-rules-do)
+- [Applying it](#applying-it) · [Dry-run first](#dry-run-first) · [Bypass actors](#bypass-actors)
+- [Enforcing queue-only merges](#enforcing-queue-only-merges) — the `update` rule,
+  what it breaks, the admin escape hatch, and how to verify
+
+### Who enforces what
+
+One ruleset, and it is worth being exact about what it does and does not do —
+this is the part most likely to be misread.
+
+**Bypass is granted per *ruleset*, never per rule.** `bypass_actors` sits on the
+ruleset; individual rules have no bypass field. An actor that bypasses one rule
+bypasses *every* rule in that ruleset.
+
+That matters because the `update` rule permits only bypass actors to write to the
+branch, so Mergify **must** be a bypass actor or it cannot merge at all. Which
+means Mergify also bypasses `required_status_checks` in the same ruleset. So the
+division of labour is:
+
+| Concern | Enforced by |
+|---|---|
+| Nobody but Mergify writes to the branch | **GitHub** — the `update` rule |
+| A red PR does not merge | **Mergify** — `merge_conditions` in `.mergify.yml` |
+| Branch not deleted or force-pushed | **GitHub** — but admins bypass |
+
+CI *is* enforced. Just by Mergify, not by GitHub. That is a real property, not a
+gap: the queue will not merge a PR whose `*gate` is red.
+
+**Why not split into two rulesets so GitHub checks Mergify too?** It was
+considered and rejected. You can put `required_status_checks` in a second ruleset
+that Mergify does not bypass — but the check being required is
+`Mergify Merge Protections`, whose pass/fail is computed from `*gate` in
+`.mergify.yml`. Weaken the gate and that check goes green along with it, so the
+second ruleset does not actually verify anything independently. It costs a second
+object to manage and buys almost nothing.
+
+If you genuinely want GitHub-side CI enforcement independent of `.mergify.yml`,
+the missing piece is not a second ruleset — it is a CI job that **always reports**
+(no `paths:` filter, or an always-run job that reports success when no gated path
+changed). Require that job directly, in a ruleset Mergify does not bypass. Until
+the job always reports, GitHub cannot require it without stranding path-exempt
+PRs, which is the whole reason the Mergify check exists as an intermediary.
+
+### Then why keep `required_status_checks` at all?
+
+With `update` active it gates nobody: non-bypass users cannot write regardless,
+and Mergify and admins bypass. It earns its place as a **backstop** — if the
+`update` rule is ever removed or the ruleset stops targeting the branch, the
+required check immediately becomes load-bearing again and ordinary users are
+still gated. Keep it, but do not mistake it for something that constrains
+Mergify's merges. It does not.
+
+### What the rules do
+
+| Rule | Why |
+|------|-----|
+| `deletion` | Nobody deletes the protected branch. |
+| `non_fast_forward` | No force-push. The queue's whole model assumes base history only moves forward. |
+| `required_status_checks` → `Mergify Merge Protections` | The one required check. **Require Mergify's check-run, not the raw CI job** — see below. |
+| `strict_required_status_checks_policy: false` | **Mandatory with `batch_size > 1`.** This is GitHub's "Require branches to be up to date before merging"; batches cannot merge with it on. |
+| `update` | **Only bypass actors may write to the branch.** This is what makes the queue mandatory — see [Enforcing Queue-Only Merges](#enforcing-queue-only-merges). Read that section first; it blocks CI bots too. |
+
+**Require the Mergify check, not the CI job.** `integration_id: 10562` is
+Mergify's GitHub App, and pinning it means only Mergify can publish the check —
+another app cannot spoof the context name. The raw CI job is the wrong thing to
+require because it is *absent*, not failing, on a path-exempt PR, and a ruleset
+cannot tell "skipped" from "missing". It would strand exactly those PRs. Mergify's
+check-run carries the same exemption logic and is always produced, so it is
+green-or-red but never missing.
+
+Verify Mergify's app id rather than trusting this document:
+
+```bash
+gh api /apps/mergify --jq '{id, slug, name}'      # → 10562
+```
+
+### Applying it
+
+`gh ruleset` is **read-only** (`list` / `view` / `check`). Creating and updating
+goes through `gh api`.
+
+```bash
+# Repository-level
+gh api -X POST /repos/<owner>/<repo>/rulesets --input ruleset.json
+
+# Update an existing one (find the id with: gh ruleset list)
+gh api -X PUT /repos/<owner>/<repo>/rulesets/<id> --input ruleset.json
+```
+
+Consider applying it once with `"enforcement": "evaluate"` first (see
+[Dry-run first](#dry-run-first)) — the `update` rule is the one most likely to
+block something you forgot about.
+
+**Org-level** rulesets cover many repos at once and need one extra condition —
+otherwise the payload is identical:
+
+```bash
+# add to conditions: "repository_name": {"include": ["~ALL"], "exclude": []}
+gh api -X POST /orgs/<org>/rulesets --input ruleset.json
+```
+
+An org-level ruleset **cannot be edited from the repository**, only viewed. If
+`gh ruleset list` shows `source_type: Organization`, take changes to the org.
+
+### Dry-run first
+
+Set `"enforcement": "evaluate"` instead of `"active"` to have GitHub record what
+*would* have been blocked without blocking it. Apply, let a few PRs land, then
+read the evaluations:
+
+```bash
+gh api '/repos/<owner>/<repo>/rulesets/rule-suites?per_page=20' \
+  --jq '.[] | {actor_name, ref, result, pushed_at}'
+```
+
+`result` is `pass` / `fail` / `bypass`. Flip to `"active"` once it reads the way
+you expect. The template ships as `"active"` deliberately — a template left in
+`evaluate` and forgotten is an unprotected branch that looks protected.
+
+### Bypass actors
+
+| `actor_type` | `actor_id` | Note |
+|---|---|---|
+| `Integration` | app id (Mergify = `10562`, GitHub Actions = `15368`) | |
+| `OrganizationAdmin` | `1` | `actor_id` is ignored for this type; `null` also works |
+| `RepositoryRole` | `5` = repository admin | Other role ids are not officially documented — copy them from an existing ruleset |
+| `Team` | team id | |
+| `DeployKey` | `null` | |
+
+`bypass_mode` is one of:
+
+| Mode | Behaviour |
+|---|---|
+| `always` | Bypasses everywhere, **and writes an audit-log entry** |
+| `pull_request` | May bypass only through a PR (branch rulesets only) |
+| `exempt` | Rules are not evaluated for this actor at all — **no audit entry** |
+
+Prefer `always` over `exempt` for anything you want a record of. `exempt` is the
+quieter setting and that is exactly its problem on a break-glass path.
+
+Exception: Mergify's own Integration actor (10562) must be `exempt` on every
+ruleset protecting the base. GitHub's async merge API, which lands
+GitHub-native stacks, honors no other mode, so the queue cannot land a stack
+with `always`. Keep human break-glass actors such as `OrganizationAdmin` on `always`.
+
+Discover ids you don't know by reading a ruleset that already has the actor you
+want:
+
+```bash
+gh api /repos/<owner>/<repo>/rulesets/<id> --jq '.bypass_actors'
+```
+
+Note that `bypass_actors` is only returned if you have write access to the
+ruleset — an empty list may mean "no permission", not "no bypasses".
+
+## Enforcing Queue-Only Merges
+
+Requiring a status check does **not** get you this. Once the check goes green,
+anyone with write access can press "Merge pull request" and the queue never sees
+the PR. To make the queue mandatory you need the ruleset's **`update`** rule:
+
+```json
+{ "type": "update", "parameters": { "update_allows_fetch_and_merge": true } }
+```
+
+GitHub calls this "Restrict updates": *only users with bypass permission can push
+to matching branches*. A PR merge is a write to the branch, so with `update` on
+the default branch and **only Mergify (plus the admin break-glass) bypassing**,
+Mergify becomes the only thing that routinely puts a commit on `main`. The merge
+button fails for everyone else. That is the enforcement — nothing in
+`.mergify.yml` can do it.
+
+`update_allows_fetch_and_merge` covers a fork's branch pulling from its upstream,
+which does not apply to a protected default branch either way; `true` matches
+GitHub's UI default.
+
+### What this breaks, and you must fix
+
+`update` blocks **every** non-bypass writer, not just humans clicking merge.
+Before enabling it, inventory anything that pushes to the protected branch and
+add it as a bypass actor, or it silently starts failing:
+
+- release automation that commits a version bump or CHANGELOG
+- `actions/github-script` or bots pushing back to `main`
+- tag-and-push release jobs
+- anything using the default `GITHUB_TOKEN` to push
+
+```bash
+# does anything push to the protected branch?
+grep -rnE 'git push|peter-evans/create-pull-request|github-script' .github/workflows/
+```
+
+A GitHub Actions push needs `{"actor_type": "Integration", "actor_id": 15368}`
+(GitHub Actions app) as a bypass actor. Verify with `gh api /apps/github-actions --jq .id`.
+
+### The admin escape hatch, routed through Mergify
+
+Once Mergify is the only writer, "an admin merges it by hand" no longer exists.
+The escape hatch has to be something *Mergify* performs. The template ships two,
+and they are not interchangeable:
+
+| | Lever | Skips CI? | Enforced? |
+|---|---|---|---|
+| **1. Jump the line** | `priority_rules` + `urgent` label | No — still queued and tested | n/a |
+| **2. Break glass** | `pull_request_rules` merge action + `emergency-merge` label | **Yes** | Convention + audit trail only |
+| **3. Lockout escape** | `OrganizationAdmin` bypass in the ruleset | Yes | Yes, by GitHub |
+
+**Reach for (1) first.** Most "this is urgent" is impatience with the queue, not
+a need to skip testing. Priority costs nothing in safety.
+
+**(2) cannot be limited to admins**, and you should know that before relying on
+it. GitHub cannot restrict who applies a label, and Mergify's `sender-permission`
+attribute only works for `@mergifyio …` **commands**, not label events. So the
+rule is a convention with an audit trail — GitHub records who applied the label,
+Mergify records and comments on the merge — not an enforced permission. There is
+no `@mergifyio merge` command to gate instead; the command set is `queue`,
+`dequeue`, `requeue`, `rebase`, `refresh`, `update`, `squash`, `backport`, `copy`.
+
+**Keep (3).** If Mergify is the only actor allowed to write to `main` and Mergify
+has an outage, the repository is frozen — nobody can merge anything, including
+the fix. `OrganizationAdmin` bypass is the way out. Use `bypass_mode: always`,
+not `exempt`: `always` writes a bypass entry to the audit log, `exempt` skips the
+rules without recording anything. For a break-glass path you want the record.
+
+Drop the `OrganizationAdmin` entry only if you consciously accept the lockout
+risk. Do not drop it by accident.
+
+You can also tighten who may enqueue at all — `queue` and `dequeue` default to
+`sender-permission >= write`:
+
+```yaml
+commands_restrictions:
+  queue:
+    conditions:
+      - sender-permission >= admin
+```
+
+### Verify it actually enforces
+
+The JSON looking right is not evidence, and the two failure directions need
+separate tests. Prove the **allowed** path first — a ruleset strict enough to
+block humans can also block Mergify if a bypass id is wrong, and you would rather
+discover that before you can no longer merge the fix.
+
+```bash
+gh ruleset list --repo <owner>/<repo>    # both rulesets present? whose are they?
+gh ruleset check main                    # confirm both apply to this branch
+
+# 1. the allowed path still works
+#    enqueue a PR with `@mergifyio queue`, then:
+mergify queue show <number> -v               # watch it through to merge
+
+# 2. the blocked path is blocked
+gh pr create --title "ruleset probe" --body "do not merge"
+gh pr merge <PR> --merge                 # MUST fail for a non-bypass user
+```
+
+Expect a rejection naming the ruleset. **If it merges anyway**, the usual causes,
+in order: you are a bypass actor yourself (org admins are — test with a non-admin
+account); the ruleset is not targeting the branch (`gh ruleset check main`); or
+`update` was left out of the queue-only ruleset, in which case the required check
+is the only gate and a green check lets anyone merge.
+
+Audit what has been landing and by whom:
+
+```bash
+gh api '/repos/<owner>/<repo>/rulesets/rule-suites?per_page=30' \
+  --jq '.[] | select(.result != "pass") | {actor_name, result, pushed_at}'
+```
+
+`result: bypass` rows are the escape hatches being used. If they are routine,
+the queue is too slow or too strict — fix that rather than normalising bypass.
+