Skip to content

feat(team): the CI runner is a brain setting, rendered into the workflows - #102

Merged
pasrom merged 3 commits into
mainfrom
feat/runner-setting
Nov 18, 2026
Merged

pasrom merged 3 commits into
mainfrom
feat/runner-setting

Conversation

@pasrom

@pasrom pasrom commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

Why

km 1.22 runs every team job on ${{ vars.KM_RUNNER || 'ubuntu-latest' }}. GitHub passes no repository or organisation variables to a fork's pull_request run unless "Send secrets and variables to workflows from fork pull requests" is on, and that also sends the secrets (observed on 2026-11-18: a fork's pull request ci run in a private repository with that option off ran on ubuntu-latest although the repository had KM_RUNNER set). So a fork's ci, the main contribution path, falls back to ubuntu-latest whatever the brain set. A literal label in ci.yml reaches that run.

What

  • Setting: runner: <label> in schema.local.yaml (default ubuntu-latest). km reads it with a small line reader in km.runner, without PyYAML, so km doctor can use it too. Where PyYAML is at hand (validate, upgrade, init, and doctor if installed), the file as YAML reads it must agree with the line, so a quoted key, runner : x, a BOM, a flow map, a block value or runner:x is refused. A value YAML would read as no string (true, on, 123, 2026-01-01, 0b101, 1.5e-3, ...) is refused too. km validate fails on it, and km upgrade stops before writing.
  • Rendering: km init --team [--runner LABEL] and km upgrade write the label into the runs-on line of every job in ci, staleness, main-guard, approve-fork-ci, review-request-guide, automerge and bump-mounted-pins.
    • bump-mounted-pins keeps MOUNTED_PINS_RUNNER first (${{ vars.MOUNTED_PINS_RUNNER || '<label>' }}). It runs only on a schedule or by hand, never on a pull request, so the variable always reaches it. It stays useful for a runner without docker.
  • Recognition:
    • A shipped copy is still km's on any label. SHIPPED keeps its earlier hashes, and a copy also counts once the runner km wrote is put back to the placeholder.
    • ci.yml is km's only on the brain's runner, on ubuntu-latest, or on 1.22's line. Without the setting, a label set by hand makes it the brain's own, so approve-fork-ci and automerge are not added or widened beside it, as on main. With the setting, km's ci.yml on another label is moved to the setting's label. An expression km did not write stays the brain's own, with a note to replace it by hand.
    • staleness.yml (it pins km) is km's when its only job is demote. It never runs on a fork's pull request, so its own steps, such as another cron, do not matter. A staleness with an extra job keeps every runs-on, with a note naming the jobs.
  • KM_RUNNER is read nowhere.
  • Tools step: the step that fetches gh, jq and yq is gated on runner.environment != 'github-hosted', so it runs on self-hosted runners only. The automerge act job keeps && needs.decide.outputs.app != '1', so the App-token job never downloads a tool. The pull_request_target jobs still never check out the pull request.

Migration (km upgrade on a 1.22.x brain)

  • km's ci.yml and staleness.yml with the vars.KM_RUNNER line (with timeout-minutes: 15) are rewritten to the brain's runner. So are older ones that have ubuntu-latest. The shipped copies are updated as usual.
  • Without the setting, the upgrade's first line starts with ATTENTION. It names every workflow that read KM_RUNNER and says they now run on ubuntu-latest. Where gh can read the variable (the repository's, else the organisation's), it gives the value and the exact runner: line to add, and never suggests a value the setting would refuse. If the setting is already there, or the variable is ubuntu-latest, a plain note says to delete the variable.
  • A changed label is re-rendered on the next upgrade (the message says "set the runner of ...").
  • If schema.local.yaml names no runner, a label set by hand in ci or staleness is left alone, with a note to move it into the setting.
  • km doctor reports:
    • a FAIL for an unusable setting;
    • a note for a workflow that still reads KM_RUNNER;
    • a note for a km workflow on a runner other than the setting;
    • the fork note for every label in ci.yml, with or without the setting;
    • a note for a readable KM_RUNNER variable, telling you to move it, or to delete it once it is moved and upgraded;
    • the security note for a non-default runner.

Tests

  • New tests/runner_smoke.sh, now run in CI. Fixtures tests/fixtures/team-1.22/ hold the 1.22.0/1.22.1 templates, which are identical. It covers:
    • init with and without --runner;
    • upgrade from 1.22 copies with and without the setting, and with and without the KM_RUNNER line;
    • a label change, a hand-set label without the setting, moved pins, an edited copy;
    • the KM_RUNNER note beside a ci.yml of the brain's own;
    • runs-on forms (an expression km never wrote, a comment);
    • the setting reader.
  • team_smoke.sh:
    • render and unrender round-trip for every template;
    • every job's runs-on is the label, and no runs-on that a pull request can start reads vars.;
    • bump-mounted-pins has no pull-request trigger;
    • the tools step is gated on runner.environment, and the App-token job never downloads;
    • ci recognition on any label, for earlier versions and for a future one.
  • runner_smoke.sh also covers:
    • a hand-set label without the setting, which adds no approve-fork-ci or automerge and does not widen a data-only one;
    • the setting taking that label over;
    • an expression in ci.yml;
    • a staleness with an extra job, and one with its own cron;
    • the ATTENTION line, with the repository's or the organisation's value, a refused value, and ubuntu-latest;
    • the YAML cross-check and the non-string labels.
  • doctor_smoke.sh: the new notes, and that TEAM_WORKFLOWS matches km.init.TEAM.
  • Mutation checks: each new rule was removed in turn and a test failed every time.
  • All smoke suites pass locally.

Plugin evals

skills/km/reference/setup.md changed. I ran the cases for its dispatch-table rows: doctor (doctor, init, upgrade) and sync. Command: claude plugin eval . --scaffold --no-publish --ablation none --allow-tools Bash Write Edit --case <case> --runs 3, on 01f92e2. The later review fixes changed nothing under skills/, so the runs still apply. No grader changed, so I ran no baseline.

case score pass runs graders
doctor 1.00 100% 3 reads-reference, runs-km-doctor
sync 1.00 100% 3 reads-reference, runs-km-sync

Not done here

  • No version bump.

…rkflow

GitHub passes no repository variables to a fork's pull_request run unless it also
passes the secrets, so ci's runs-on: ${{ vars.KM_RUNNER || 'ubuntu-latest' }} sent a
fork's ci, the main contribution path, to GitHub's runners. The runner is now
runner: <label> in schema.local.yaml (default ubuntu-latest), read by a line reader
that km validate, km upgrade and km doctor cross-check against YAML where PyYAML is
at hand: km init --team (--runner) and km upgrade write it as a literal into every
runs-on line. bump-mounted-pins keeps MOUNTED_PINS_RUNNER first: it never runs on a
pull request. The tools step runs on self-hosted runners (runner.environment), never
in automerge's App-token job.

A shipped copy with any runner written into it is still km's (SHIPPED is checked
with the runner put back). ci.yml is km's on the brain's runner only: without the
setting a label set by hand makes it the brain's own, so no approve-fork-ci or
automerge is added or widened beside it. km upgrade rewrites km 1.22's KM_RUNNER line
in ci.yml and staleness.yml, says first that the jobs moved to ubuntu-latest with the
variable's value where gh reads it, re-renders a changed label, and leaves a
staleness.yml with a job of the brain's own.
…o longer reads

A setting km cannot use fails; a workflow still reading KM_RUNNER, or on another
runner than the setting, gets a note to run km upgrade; a KM_RUNNER variable gh can
read gets a note to move it into the setting and delete it; a runner other than
ubuntu-latest gets the note that a fork's pull request runs ci there.
@pasrom
pasrom force-pushed the feat/runner-setting branch from 01f92e2 to e5ffaf1 Compare November 18, 2026 13:06
@pasrom
pasrom merged commit 27babc9 into main Nov 18, 2026
5 checks passed
@pasrom
pasrom deleted the feat/runner-setting branch November 18, 2026 13:23
@pasrom pasrom mentioned this pull request Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant