From 5038acbe44868a384067f6feabcb54dc0983aa71 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 27 Oct 2026 17:13:14 -0700 Subject: [PATCH 1/4] chore(quest): claim quest/m1/land.md Quest-Claim: 4ab8057807151749 From f8a0c0e4bcb0713c57b4766764379ed3fe2e6a14 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 27 Oct 2026 17:16:50 -0700 Subject: [PATCH 2/4] ci: land main through quest land The Land workflow batches PRs queued with `quest merge --land`, checks the chain with Check's steps once, and fast-forwards main to the passing prefix. It pushes with a land App's token from the `land` environment; a test keeps every other job out of that environment. Check drops its merge_group and push-to-main triggers. Co-Authored-By: Claude Opus 5.5 --- .github/land.test.sh | 33 +++++++++++ .github/workflows/check.yml | 6 +- .github/workflows/land.yml | 107 ++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 6 +- justfile | 7 ++- quest/m1/land.md | 29 +++++++--- 6 files changed, 171 insertions(+), 17 deletions(-) create mode 100644 .github/land.test.sh create mode 100644 .github/workflows/land.yml diff --git a/.github/land.test.sh b/.github/land.test.sh new file mode 100644 index 000000000..03c015695 --- /dev/null +++ b/.github/land.test.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +# The `land` environment holds the key of the App that main's ruleset lets bypass it, +# so only the Land workflow's land job may name it. +set -euo pipefail + +# Print `workflow:job` for every job in the given workflows that names the `land` environment. +users() { + awk ' + FNR == 1 { job = "workflow"; mapping = 0 } + # Jobs sit two spaces under the top-level `jobs:`. + /^ [A-Za-z0-9_-]+:[ \t]*$/ { job = $1; sub(/:$/, "", job) } + # The mapping form puts `name:` on the line after `environment:`. + (mapping && /^[ \t]*name:[ \t]*["\047]?land["\047]?[ \t]*$/) || /^[ \t]*environment:.*\/ { + n = split(FILENAME, path, "/") + print path[n] ":" job + } + { mapping = /^[ \t]*environment:[ \t]*$/ } + ' "$@" +} + +fixture=$(mktemp -d) +trap 'rm -rf "$fixture"' EXIT +printf 'jobs:\n build:\n environment: land\n' >"$fixture/scalar.yml" +printf 'jobs:\n build:\n environment:\n name: land\n' >"$fixture/mapping.yml" +printf 'jobs:\n build:\n environment: release\n' >"$fixture/other.yml" +[[ $(users "$fixture/scalar.yml" "$fixture/mapping.yml" "$fixture/other.yml") == $'scalar.yml:build\nmapping.yml:build' ]] + +workflows=$(cd "$(dirname "$0")" && pwd)/workflows +found=$(users "$workflows"/*.yml) +if [[ $found != land.yml:land ]]; then + printf 'only land.yml:land may use the land environment, found:\n%s\n' "$found" >&2 + exit 1 +fi diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index db1355058..172abe403 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -3,12 +3,10 @@ name: Check permissions: contents: read +# Not on a push to main: main only fast-forwards to a tree land.yml already checked. on: pull_request: - merge_group: - push: - branches: - - main + workflow_dispatch: # Cancel in-flight runs when a new commit lands on the same ref. concurrency: diff --git a/.github/workflows/land.yml b/.github/workflows/land.yml new file mode 100644 index 000000000..e5a64684e --- /dev/null +++ b/.github/workflows/land.yml @@ -0,0 +1,107 @@ +name: Land + +# `quest land` batches the PRs queued with `quest merge --land`: it squashes them +# onto main, checks the chain once, and fast-forwards main to the passing prefix. +on: + pull_request_target: + types: [auto_merge_enabled] + workflow_dispatch: + +# One run at a time; waiting triggers collapse into one run that reads the whole queue. +concurrency: + group: land + +permissions: {} + +jobs: + resolve: + runs-on: ubuntu-24.04-arm + timeout-minutes: 15 + permissions: { contents: read, pull-requests: read, checks: read, statuses: read } + outputs: + plan: ${{ steps.resolve.outputs.plan }} + steps: + # Every job checks out main, so quest comes from a pin no queued PR can modify. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: ./.github/actions/nix + - name: Build quest + run: | + nix build --out-link "$RUNNER_TEMP/quest" .#quest + echo "$RUNNER_TEMP/quest/bin" >> "$GITHUB_PATH" + - id: resolve + env: + GH_TOKEN: ${{ github.token }} + run: echo "plan=$(quest land resolve)" >> "$GITHUB_OUTPUT" + + check: + needs: resolve + runs-on: ubuntu-24.04-arm + # Room for a few runs of Check's steps: a failing chain is bisected until a prefix passes. + timeout-minutes: 90 + # This job runs the queued PRs' code, so it holds only a read token. + permissions: { contents: read } + outputs: + result: ${{ steps.check.outputs.result }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + - uses: ./.github/actions/nix + # Built outside the checkout before the chain replaces it. + - name: Build quest + run: | + nix build --out-link "$RUNNER_TEMP/quest" .#quest + echo "$RUNNER_TEMP/quest/bin" >> "$GITHUB_PATH" + # The same steps as check.yml's Check job. + - id: check + env: + PLAN: ${{ needs.resolve.outputs.plan }} + run: | + git config user.name 'github-actions[bot]' + git config user.email '41898282+github-actions[bot]@users.noreply.github.com' + printf '%s' "$PLAN" > "$RUNNER_TEMP/plan.json" + echo "result=$(quest land check "$RUNNER_TEMP/plan.json" -- nix develop --command bash -c 'just check && just test')" >> "$GITHUB_OUTPUT" + + land: + needs: [resolve, check] + runs-on: ubuntu-24.04-arm + timeout-minutes: 15 + # The environment, which only main can deploy to, holds the key of the App + # that main's ruleset lets bypass it. Only this job may use it. + environment: land + # contents: write lets github.token disable auto-merge when it ejects a PR. + permissions: { contents: write, pull-requests: write, issues: write, actions: write, checks: read, statuses: read } + steps: + - id: app + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 + with: + client-id: ${{ vars.LAND_APP_CLIENT_ID }} + private-key: ${{ secrets.LAND_APP_PRIVATE_KEY }} + # Workflows lets it land PRs that change this directory. + permission-contents: write + permission-workflows: write + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + token: ${{ steps.app.outputs.token }} + - uses: ./.github/actions/nix + - name: Build quest + run: | + nix build --out-link "$RUNNER_TEMP/quest" .#quest + echo "$RUNNER_TEMP/quest/bin" >> "$GITHUB_PATH" + - env: + GH_TOKEN: ${{ github.token }} + PLAN: ${{ needs.resolve.outputs.plan }} + RESULT: ${{ needs.check.outputs.result }} + run: | + git config user.name 'github-actions[bot]' + git config user.email '41898282+github-actions[bot]@users.noreply.github.com' + printf '%s' "$PLAN" > "$RUNNER_TEMP/plan.json" + printf '%s' "$RESULT" > "$RUNNER_TEMP/result.json" + quest land push "$RUNNER_TEMP/plan.json" "$RUNNER_TEMP/result.json" > "$RUNNER_TEMP/landing" + cat "$RUNNER_TEMP/landing" + # The queue changed, so run again for the rest. + if [ -s "$RUNNER_TEMP/landing" ]; then gh workflow run land.yml --ref "$GITHUB_REF_NAME"; fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 896cd9470..fba3bbe0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,8 @@ # Commits -PRs into `main` are squash-merged, so the PR title becomes the commit subject and the PR description becomes the body. +PRs land on `main` only through `quest land`, each as one squash commit: the PR title becomes the commit subject and the PR's commit messages become the body. +Queue a PR with `quest merge --land ` (`/quest-merge` does this), and the Land workflow runs Check's steps once on the batch, landing the longest passing prefix. +The admin bypass of `main`'s ruleset is for emergencies. - Use conventional-commit subjects (`feat(ts): ...`, `fix: ...`, `chore: ...`, `docs: ...`). - AI commit attribution goes in a `Co-Authored-By:` trailer, not the commit body. @@ -29,7 +31,7 @@ For each finding: - If you don't agree with it, reply to the finding and move on. - If it's a relatively easy improvement, fix it and push. -Merge only after a review from a reviewer other than Grok has no findings, or every finding is fixed or replied to. +Queue a PR only after a review from a reviewer other than Grok has no findings, or every finding is fixed or replied to. # Follow-ups diff --git a/justfile b/justfile index a49d676c7..7527ae129 100644 --- a/justfile +++ b/justfile @@ -20,8 +20,8 @@ default: check: quest check actionlint - shellcheck .claude/hooks/*.sh .codex/hooks/*.sh bench/*/*.sh - shfmt -d .claude/hooks/*.sh .codex/hooks/*.sh bench/*/*.sh + shellcheck .claude/hooks/*.sh .codex/hooks/*.sh .github/*.sh bench/*/*.sh + shfmt -d .claude/hooks/*.sh .codex/hooks/*.sh .github/*.sh bench/*/*.sh taplo format --check nixfmt --check flake.nix bench/build/nix.nix cargo fmt --all --check @@ -34,6 +34,7 @@ check: # Run the tests. test: bash .claude/hooks/direnv.test.sh + bash .github/land.test.sh just ts test just ffi test just driver test @@ -53,7 +54,7 @@ bench-ffi *args: # Apply formatters without changing program behavior. fix: - shfmt -w .claude/hooks/*.sh .codex/hooks/*.sh bench/*/*.sh + shfmt -w .claude/hooks/*.sh .codex/hooks/*.sh .github/*.sh bench/*/*.sh taplo format nixfmt flake.nix bench/build/nix.nix cargo fmt --all diff --git a/quest/m1/land.md b/quest/m1/land.md index f754ad4b6..fc07bb7dd 100644 --- a/quest/m1/land.md +++ b/quest/m1/land.md @@ -1,4 +1,4 @@ -# [S] Land main through quest land +# [XS] Land main through quest land ## Goal @@ -13,10 +13,23 @@ Decided 2026-10-26 (maintainer), planning moq-dev/moq's merge throughput ([moq-dev/moq#6854](https://github.com/moq-dev/moq/pull/6854)): the batched gate is shared through kixelated/quest, and this repository adopts it. -- The push credential is GitHub Actions in a new `main` ruleset's bypass - list, guarded by a test that refuses `contents: write` anywhere but the - land job, as moq.pro's `queue.test.ts` does. The admin role keeps its - emergency bypass. Ruleset writes are the maintainer's. -- The ruleset requires a check that PR heads never carry, so auto-merge only - waits for the gate. `check.yml` drops its `merge_group` trigger. -- Update the contributor docs that describe landing. +[kixelated/rust2#137](https://github.com/kixelated/rust2/pull/137) added the +Land workflow, a test that only its land job uses the `land` environment, and +`CONTRIBUTING.md`'s landing rule. What remains is the maintainer's setup and +the live verification. + +- **Push credential (maintainer).** A GitHub App installed on this repository + is the `main` ruleset's bypass actor, with Contents and Workflows write + (Workflows lets it land PRs that change `.github/workflows`) and no + webhook. GitHub Actions cannot be: rulesets refused it as a bypass actor on + a personal repository, kixelated/quest, on 2026-10-27. The `land` + environment, deployable only from `main`, holds the App's client ID as the + variable `LAND_APP_CLIENT_ID` and its key as the secret + `LAND_APP_PRIVATE_KEY`. +- **Ruleset (maintainer).** A new `main` ruleset blocks deletion and + non-fast-forward pushes and requires two checks: `Check` from GitHub + Actions, and `quest land` pinned to the land App, which has no checks or + statuses permission and so never reports it. Its bypass actors are the land + App and the admin role, which keeps an emergency bypass. Ruleset writes are + the maintainer's. +- The PR that finishes this quest lands through the gate, verifying it. From 4bc85e4691aa5b8354843733b4c470b339ed2dd8 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Wed, 28 Oct 2026 09:51:58 -0700 Subject: [PATCH 3/4] ci: parse workflows to guard the land environment The line scan read only `*.yml` and could miss an environment spelled through an expression, a flow mapping, or another repository's reusable workflow. Parse every `*.yml` and `*.yaml` workflow and allow no environment and no remote reusable workflow outside land.yml's land job. Co-Authored-By: Claude Opus 5.5 --- .github/land.test.sh | 33 --------------------------------- .github/land.test.ts | 34 ++++++++++++++++++++++++++++++++++ justfile | 8 ++++---- 3 files changed, 38 insertions(+), 37 deletions(-) delete mode 100644 .github/land.test.sh create mode 100644 .github/land.test.ts diff --git a/.github/land.test.sh b/.github/land.test.sh deleted file mode 100644 index 03c015695..000000000 --- a/.github/land.test.sh +++ /dev/null @@ -1,33 +0,0 @@ -#!/usr/bin/env bash -# The `land` environment holds the key of the App that main's ruleset lets bypass it, -# so only the Land workflow's land job may name it. -set -euo pipefail - -# Print `workflow:job` for every job in the given workflows that names the `land` environment. -users() { - awk ' - FNR == 1 { job = "workflow"; mapping = 0 } - # Jobs sit two spaces under the top-level `jobs:`. - /^ [A-Za-z0-9_-]+:[ \t]*$/ { job = $1; sub(/:$/, "", job) } - # The mapping form puts `name:` on the line after `environment:`. - (mapping && /^[ \t]*name:[ \t]*["\047]?land["\047]?[ \t]*$/) || /^[ \t]*environment:.*\/ { - n = split(FILENAME, path, "/") - print path[n] ":" job - } - { mapping = /^[ \t]*environment:[ \t]*$/ } - ' "$@" -} - -fixture=$(mktemp -d) -trap 'rm -rf "$fixture"' EXIT -printf 'jobs:\n build:\n environment: land\n' >"$fixture/scalar.yml" -printf 'jobs:\n build:\n environment:\n name: land\n' >"$fixture/mapping.yml" -printf 'jobs:\n build:\n environment: release\n' >"$fixture/other.yml" -[[ $(users "$fixture/scalar.yml" "$fixture/mapping.yml" "$fixture/other.yml") == $'scalar.yml:build\nmapping.yml:build' ]] - -workflows=$(cd "$(dirname "$0")" && pwd)/workflows -found=$(users "$workflows"/*.yml) -if [[ $found != land.yml:land ]]; then - printf 'only land.yml:land may use the land environment, found:\n%s\n' "$found" >&2 - exit 1 -fi diff --git a/.github/land.test.ts b/.github/land.test.ts new file mode 100644 index 000000000..2cef57ef7 --- /dev/null +++ b/.github/land.test.ts @@ -0,0 +1,34 @@ +// The `land` environment holds the key of the App that main's ruleset lets bypass it, +// so only the Land workflow's land job may name an environment. Any other environment +// reference counts, since an expression can spell `land` without the word. +import { deepStrictEqual } from "node:assert"; +import { readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +type Job = { environment?: unknown; uses?: unknown }; + +/** The `workflow:job` of every job that names an environment or calls another repository's workflow, which could. */ +function users(name: string, text: string): string[] { + const jobs: Record = Bun.YAML.parse(text)?.jobs ?? {}; + return Object.entries(jobs) + .filter(([, job]) => job.environment !== undefined || (typeof job.uses === "string" && !job.uses.startsWith("./"))) + .map(([id]) => `${name}:${id}`); +} + +const fixtures: [string, string[]][] = [ + ["jobs:\n build:\n environment: land\n", ["ci.yml:build"]], + ["jobs:\n build:\n environment:\n name: land\n", ["ci.yml:build"]], + ["jobs:\n build: { environment: { name: land } }\n", ["ci.yml:build"]], + ["jobs:\n build:\n environment: ${{ format('{0}nd', 'la') }}\n", ["ci.yml:build"]], + ["jobs:\n build:\n uses: someone/else/.github/workflows/steal.yml@main\n", ["ci.yml:build"]], + ["jobs:\n build:\n uses: ./.github/workflows/check.yml\n", []], + ["jobs:\n build:\n runs-on: ubuntu-latest\n", []], +]; +for (const [text, expected] of fixtures) deepStrictEqual(users("ci.yml", text), expected, text); + +// GitHub runs both extensions. +const workflows = join(import.meta.dir, "workflows"); +const found = readdirSync(workflows) + .filter((name) => /\.ya?ml$/.test(name)) + .flatMap((name) => users(name, readFileSync(join(workflows, name), "utf8"))); +deepStrictEqual(found, ["land.yml:land"], "only land.yml's land job may name an environment"); diff --git a/justfile b/justfile index 7527ae129..ab666ed27 100644 --- a/justfile +++ b/justfile @@ -20,8 +20,8 @@ default: check: quest check actionlint - shellcheck .claude/hooks/*.sh .codex/hooks/*.sh .github/*.sh bench/*/*.sh - shfmt -d .claude/hooks/*.sh .codex/hooks/*.sh .github/*.sh bench/*/*.sh + shellcheck .claude/hooks/*.sh .codex/hooks/*.sh bench/*/*.sh + shfmt -d .claude/hooks/*.sh .codex/hooks/*.sh bench/*/*.sh taplo format --check nixfmt --check flake.nix bench/build/nix.nix cargo fmt --all --check @@ -34,7 +34,7 @@ check: # Run the tests. test: bash .claude/hooks/direnv.test.sh - bash .github/land.test.sh + bun .github/land.test.ts just ts test just ffi test just driver test @@ -54,7 +54,7 @@ bench-ffi *args: # Apply formatters without changing program behavior. fix: - shfmt -w .claude/hooks/*.sh .codex/hooks/*.sh .github/*.sh bench/*/*.sh + shfmt -w .claude/hooks/*.sh .codex/hooks/*.sh bench/*/*.sh taplo format nixfmt flake.nix bench/build/nix.nix cargo fmt --all From 1349259388552cac8034c3652dd9bdfd759b8a02 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Wed, 28 Oct 2026 09:52:09 -0700 Subject: [PATCH 4/4] quest: name the guard's wider rule Co-Authored-By: Claude Opus 5.5 --- quest/m1/land.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quest/m1/land.md b/quest/m1/land.md index fc07bb7dd..6e004a654 100644 --- a/quest/m1/land.md +++ b/quest/m1/land.md @@ -14,7 +14,7 @@ Decided 2026-10-26 (maintainer), planning moq-dev/moq's merge throughput gate is shared through kixelated/quest, and this repository adopts it. [kixelated/rust2#137](https://github.com/kixelated/rust2/pull/137) added the -Land workflow, a test that only its land job uses the `land` environment, and +Land workflow, a test that only its land job names an environment, and `CONTRIBUTING.md`'s landing rule. What remains is the maintainer's setup and the live verification.