The shared landing system for every public repo in the fleet: one required check
(gate), the full suite run once per PR, and auto-merge through GitHub Merge Queue where
GitHub offers one.
| Path | What it is |
|---|---|
actions/gate |
Composite action. Fails unless every job the caller's gate job needs ended exactly as expected: success where it should run, skipped where it shouldn't. |
.github/workflows/auto-merge.yml |
Reusable. Arms squash auto-merge on same-repo, non-draft, non-Dependabot PRs, using a GitHub App token. |
.github/workflows/arm-dependabot.yml |
Reusable. Arms Dependabot PRs from a schedule. A Dependabot-triggered run can't read the App key. |
.github/workflows/status-labels.yml |
Reusable. Keeps auto-merge (green) and merge-queue (purple) labels in sync with the live PR state, so they show up in the PR list. Derived on every event, never trusted. Its header has the caller snippet. |
rulesets/main.json, rulesets/merge-queue.json |
The default-branch ruleset: squash only, gate required (from GitHub Actions only), admin bypass. Plus the queue rule. |
scripts/apply-ruleset.sh |
Makes a repo match the ruleset. Dry run by default. |
GitHub offers a merge queue only on public repos owned by an organization. The tier is derived from that, never chosen by hand:
| Tier | Repos | The heavy suite runs | Landing |
|---|---|---|---|
| A | org-owned + public | once, in the merge queue (vars.QUEUE_ENABLED == 'true') |
merge queue |
| B | everything else | once, on the PR | auto-merge |
Fork PRs run the heavy suite on the PR in both tiers. A contributor sees a real failure before review, not a queue ejection that only a maintainer can retry.
on:
pull_request:
merge_group:
types: [checks_requested]
workflow_dispatch:
concurrency:
group: ci-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }} # never cancel a queue run
permissions:
contents: read # no secrets in CI: merge_group runs fork code in base-repo context
jobs:
quick: # optional, cheap, never required
if: github.event_name == 'pull_request'
heavy: # the repo's real suite; any number of jobs with this if:
if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || vars.QUEUE_ENABLED != 'true'
gate: # THE ONLY REQUIRED CHECK; never rename it
if: ${{ !cancelled() }}
needs: [quick, heavy]
runs-on: ubuntu-24.04
steps:
- uses: kattakath/.github/actions/gate@<sha>
with:
needs: ${{ toJSON(needs) }}
# A deliberate second copy of heavy's if:. If the two copies drift, gate goes red.
expect: >-
{"quick": ${{ github.event_name == 'pull_request' }},
"heavy": ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || vars.QUEUE_ENABLED != 'true' }}}Then:
- Add the
auto-merge,arm-dependabotandstatus-labelscallers. Each reusable file's header has the snippet. - Merge that PR under the repo's current rules.
- Run
scripts/apply-ruleset.sh OWNER/REPOand read the diff, then re-run with--apply.- On Tier A it sets
QUEUE_ENABLEDonly after the queue rule exists. - It refuses to replace a ruleset that requires checks other than
gate.
- On Tier A it sets
- Open WIP PRs as drafts.
gategoes green on a PR in seconds, so an armed PR is queued at once.
- Never put
[skip ci]in a branch commit. A squash merge copies every branch commit's message into the merge commit, so the tag silencesmain's push workflows too (deploys, publish chains). ismailkattakath/userscripts #15 skipped itslintpush run, andpublishstayed one commit behind until it was dispatched by hand. - A queued run can be starved of runners. GitHub-hosted macOS arm64 capacity ran out, and
the job "was not acquired by Runner of type hosted even after multiple attempts". After
15 min it was cancelled,
gatewent red (correctly), and the queue ejected the PR (kattakath/ircc-whatsapp-bot #16). Re-run the PR'sarmjob to re-queue it. Prefer Linux runners for the heavy leg wherever the suite allows. - Expressions inside an action input's
descriptionare evaluated. A${{ … }}in a description fails the action at load time. - Old actionlint versions reject
enqueued/dequeuedonpull_request_target. GitHub's docs allow both. Use actionlint ≥ 1.7.12.
- Measured gain: on kattakath/skills the heavy suite ran twice per PR (~96 s on the PR,
~101 s again on
push: main). Under the queue it runs once: #174 ran 84 s inmerge_group, and its PR run skipped it. - Why an aggregator: "A job that is skipped will report its status as Success" (GitHub
docs), so a skippable job must never be the required check. Prior art: indexmap,
DeterminateSystems/magic-nix-cache-action. The rejected alternative was skipping the
required job itself (boinkor/governor). It's fragile once that job gains a
needs:. - The ejection is proven: kattakath/skills #175 failed in the queue, and the queue removed it unmerged.
MIT licensed.