@futurelastic/colab-handbook 1.20.4-rc.8 → 1.21.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/audit/audit.mjs CHANGED
@@ -123,6 +123,8 @@ const npmGuard = require("../tools/lib/npm-publish-guard.js");
123
123
  const installRoute = require("../tools/lib/install-route.js");
124
124
  const releaseRunner = require("../tools/lib/release-runner.js"); // #453
125
125
  const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
126
+ // #721: a copied CI gate, or one that never skips, is drift — the pure reading lives with its tests.
127
+ const gateDrift = require("../tools/lib/gate-drift.js");
126
128
  const shipBatch = require("../tools/lib/ship-batch.js");
127
129
  const integrationProfile = require("../tools/lib/integration-profile.js"); // #610
128
130
  const ciProfile = require("../tools/lib/ci-profile.js"); // #559
@@ -584,6 +586,13 @@ function listRemoteDir(slug, path) {
584
586
  }
585
587
  }
586
588
 
589
+ // #721: one GitHub REST read, parsed — null when it could not be read (offline, no auth, an API error).
590
+ function readRemoteJson(slug, path) {
591
+ const r = remoteCache.get(slug, `repos/${slug}/${path}`);
592
+ if (r.status !== "ok") return null;
593
+ try { return JSON.parse(r.text); } catch { return null; }
594
+ }
595
+
587
596
  function listRemoteBranches(slug) {
588
597
  const r = remoteCache.get(slug, `repos/${slug}/branches`, { paginate: true });
589
598
  return r.status === "ok" ? r.items.map((b) => String(b.name)) : null; // null = could not determine, distinct from "no branches"
@@ -872,6 +881,12 @@ function makeSource(target) {
872
881
  const slug = url ? githubSlugFromRemote(url) : null;
873
882
  return slug ? readRemoteIssue(slug, num) : null;
874
883
  },
884
+ // #721: a REST read under repos/<slug>/ on the same resolved remote; null = unreadable.
885
+ ghApi: (p) => {
886
+ const url = gitRemote.remoteUrl(root);
887
+ const slug = url ? githubSlugFromRemote(url) : null;
888
+ return slug ? readRemoteJson(slug, p) : null;
889
+ },
875
890
  // Same remote-slug resolution as labels() above, one API call, and only when the
876
891
  // identity scan was explicitly asked for — see readRemoteMetadata for the contract.
877
892
  // An unresolvable remote is its own status, not "no-remote": the scan was asked for
@@ -930,6 +945,7 @@ function makeSource(target) {
930
945
  isLinkedWorktree: () => false,
931
946
  labels: () => listRemoteLabels(target.slug),
932
947
  issue: (num) => readRemoteIssue(target.slug, num),
948
+ ghApi: (p) => readRemoteJson(target.slug, p),
933
949
  // Anchor-link check is local-only by design (#158) — enumerating markdown remotely
934
950
  // would be N `gh api` calls per repo across a fleet sweep. Empty list = the check
935
951
  // scans nothing and emits nothing for a remote source, matching checkRunbook's
@@ -2187,6 +2203,8 @@ function auditRepoInner(target, ctx) {
2187
2203
  info.predatesAxes = [];
2188
2204
  info.suggestions = [];
2189
2205
  const suggest = (t) => info.suggestions.push(t);
2206
+ // #721: the CI dedupe gate maintained once — a copy of it, or a gate that never skips, is drift.
2207
+ checkGateDrift(src, workflows, cfg?.trunk ?? null, warn, { self: isSelf, suggest });
2190
2208
  if (integrationSuggestion) suggest(integrationSuggestion); // #610
2191
2209
  if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw, suggest });
2192
2210
 
@@ -2853,6 +2871,58 @@ function checkInstructionFilesCaller(src, workflows, trunk, warn) {
2853
2871
  for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
2854
2872
  }
2855
2873
 
2874
+ // ---- CI gate drift (#721) ----------------------------------------------------
2875
+ // The dedupe gate lives once, in the handbook's reusable workflow (.github/workflows/ci-light.yml).
2876
+ // Two readings, both warn (drift, not customisation — the repo still owns its files):
2877
+ // 1. a workflow carrying its own copy of the gate instead of calling ci-light.yml — static, always;
2878
+ // 2. a guarded workflow whose last N trunk push runs never skipped although one landed a tree another
2879
+ // ref had already passed green — read from run history, so only where GitHub can be read.
2880
+ // The handbook itself is the source: its ci.yml and ci-light.yml carry the gate by design, so the
2881
+ // static reading is off here (self-audit); the history reading still runs.
2882
+ // Reading 1 is a warn only once the handbook's latest release tag carries ci-light.yml: before that
2883
+ // there is nothing to switch TO (a caller pins a tag), so it is a suggestion — the #607 posture for a
2884
+ // CI copy — and it turns into drift by itself the day a release ships the workflow.
2885
+ let reusableReleasedMemo;
2886
+ function reusableReleased() {
2887
+ if (reusableReleasedMemo !== undefined) return reusableReleasedMemo;
2888
+ const hb = handbookInfo(HANDBOOK_ROOT);
2889
+ reusableReleasedMemo = false;
2890
+ if (hb.hasGit && !hb.untagged) {
2891
+ try {
2892
+ execFileSync("git", ["-C", HANDBOOK_ROOT, "cat-file", "-e", `${hb.version}:${gateDrift.REUSABLE_PATH}`], { stdio: "ignore" });
2893
+ reusableReleasedMemo = hb.version;
2894
+ } catch { reusableReleasedMemo = false; }
2895
+ }
2896
+ return reusableReleasedMemo;
2897
+ }
2898
+ function checkGateDrift(src, workflows, trunk, warn, { self = false, suggest = () => {} } = {}) {
2899
+ const { callers, copies } = gateDrift.copiedGates({ readFile: (p) => src.readFile(p), workflows });
2900
+ if (!self && copies.length) {
2901
+ const released = reusableReleased();
2902
+ for (const wf of copies) {
2903
+ if (released) warn(gateDrift.copiedGateText(wf));
2904
+ else suggest(`${wf}: ${gateDrift.copiedGateText(wf)} — a suggestion until a handbook release tag carries ${gateDrift.REUSABLE_PATH}`);
2905
+ }
2906
+ }
2907
+ if (!trunk || typeof src.ghApi !== "function") return;
2908
+ for (const wf of [...callers, ...copies]) {
2909
+ if (self && wf === "ci-light.yml") continue; // the callee: its runs are its callers'
2910
+ const q = (p) => src.ghApi(`actions/workflows/${encodeURIComponent(wf)}/${p}`);
2911
+ const trunkList = q(`runs?branch=${encodeURIComponent(trunk)}&event=push&status=completed&per_page=${gateDrift.RECENT_TRUNK_RUNS}`);
2912
+ if (!trunkList || !Array.isArray(trunkList.workflow_runs)) continue; // unreadable or offline — say nothing
2913
+ const greenList = q("runs?event=push&status=success&per_page=50"); // the guard's own window (#493)
2914
+ if (!greenList || !Array.isArray(greenList.workflow_runs)) continue;
2915
+ const tree = (r) => (r.head_commit && r.head_commit.tree_id) || null;
2916
+ const trunkRuns = trunkList.workflow_runs.slice(0, gateDrift.RECENT_TRUNK_RUNS).map((r) => {
2917
+ const j = src.ghApi(`actions/runs/${r.id}/jobs?per_page=100`);
2918
+ return { id: r.id, tree: tree(r), created: r.created_at, jobs: j && Array.isArray(j.jobs) ? j.jobs : null };
2919
+ });
2920
+ const greenRuns = greenList.workflow_runs.map((r) => ({ id: r.id, branch: r.head_branch, tree: tree(r), created: r.created_at }));
2921
+ const r = gateDrift.gateNeverSkips({ trunkRuns, greenRuns, trunk });
2922
+ if (r.verdict === "drift") warn(gateDrift.inertGateText(wf, r));
2923
+ }
2924
+ }
2925
+
2856
2926
  // ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
2857
2927
  // The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
2858
2928
  // same finding; this maps its severity onto the audit's fail/warn.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.20.4-rc.8"
36
+ "version": "1.21.0-rc.1"
37
37
  }
@@ -2,10 +2,11 @@
2
2
 
3
3
  Starting points you **copy into your own repo**. That is the entire model.
4
4
 
5
- > **These are NOT called remotely — with one exception.** `instruction-files.yml` is a caller:
5
+ > **These are NOT called remotely — with two exceptions.** `instruction-files.yml` is a caller:
6
6
  > its one job `uses:` this handbook's reusable `.github/workflows/instruction-files.yml` (#588,
7
- > kept for compatibility — see *Where each file lives* below). Every other file here is copied,
8
- > not called. (`dist-refs.yml` is a
7
+ > kept for compatibility — see *Where each file lives* below). `ci-call.yml` is the other: it calls
8
+ > the reusable light lane `.github/workflows/ci-light.yml`, pinned to a release tag (#721 — see
9
+ > *The reusable light lane* below). Every other file here is copied, not called. (`dist-refs.yml` is a
9
10
  > `workflow_call` workflow, but its caller is your own release workflow, in the same repo, via
10
11
  > `uses: ./.github/workflows/dist-refs.yml` — the file still lives, in full, where it runs.) An earlier version of this
11
12
  > handbook told repos to call shared workflows; that was reversed. Every other workflow now
@@ -102,6 +103,7 @@ check that reads one of these files is that tool's behaviour, documented with th
102
103
 
103
104
  | File | Copy to | For | Notes |
104
105
  |---|---|---|---|
106
+ | `ci-call.yml` | `.github/workflows/ci.yml` | Any Node, Python or Laravel repo that wants the light lane **called, not copied** (#721) | **A caller, not a copy:** triggers, concurrency and one `uses:` of the handbook's reusable `.github/workflows/ci-light.yml` — the dedupe gate, the secret scan, a `quick` and a `full` job, job-class `runs-on`. `colab template ci-call` writes this repo's trunk refs and pins the call to the release it stamps. Your commands go in `with:` (`toolchain`, `install`, `quick`, `full`); your own jobs sit beside the call. A copied gate is reported as drift. |
105
107
  | `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | Resolves Node version from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. Opt-in `Migration round-trip` job — `--roundtrip` writes it live, see *Migration round-trip* below. |
106
108
  | `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
107
109
  | `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step; the `secrets` job's gitleaks install and `GITLEAKS_VERSION` likewise follow the light lane's `gitleaks` job. `TRUNK` is an edit point. |
@@ -176,6 +178,26 @@ The rule all of this keeps: [one verdict per tree](../CONVENTIONS.md#one-verdict
176
178
  Opt out with `tree-reuse: off` (`project.schema.md`) when trunk's run proves something a branch
177
179
  run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned runner images.
178
180
 
181
+ ### The reusable light lane — calling instead of copying (#721)
182
+
183
+ The guard above drifted copy by copy: measured across adopters (2026-11-09 → 11-11), missing in six
184
+ repositories and present but never skipping in three, and #717's fix reached a copy only through a manual
185
+ sync. `.github/workflows/ci-light.yml` carries the same guard, the same secret scan and the descriptor check
186
+ once, for every caller; `ci-call.yml` is the caller. What changes for you:
187
+
188
+ - **Only the caller is yours**: the triggers and `concurrency` (a called workflow cannot own either), the
189
+ `with:` block, and your own jobs beside the call. A job behind the gate reads `needs: ci` +
190
+ `if: ${{ !cancelled() && needs.ci.outputs.tested != 'true' }}`; a trunk-only job outside it is named
191
+ in `trunk-only-jobs` (#717).
192
+ - **Pinned to a release tag, never `main`.** `colab template ci-call` writes the version it stamps the copy
193
+ with; `colab update` moves a pristine copy's stamp and pin together.
194
+ - **The quick/full split is two jobs**: `quick` (descriptor check, lint, types, unit — the `quick` class)
195
+ and `full` (the light suite, the build — the `full` class); both run on every push the gate does not skip,
196
+ and both take the `trunk` class on a trunk ref under `runs-on: classes`.
197
+ - The copied `ci-<stack>.yml` templates still work and are still copied; moving them onto the caller is
198
+ tracked in #724. A repo carrying one is reported as drift — a suggestion until a handbook release tag carries
199
+ `ci-light.yml`, a warning from then on.
200
+
179
201
  ### Migration round-trip — have it from the first copy
180
202
 
181
203
  `migration-grant: reviewer` grants only where a `Migration round-trip…` job passed at the
@@ -428,8 +450,8 @@ Decided 2026-07-19, after a GitHub Actions billing lock stopped every
428
450
  | Repo class | `runs-on` | Why |
429
451
  |---|---|---|
430
452
  | **Public** repo | `ubuntu-latest` | Free minutes, unaffected by billing — and **never** self-hosted: a fork PR would execute arbitrary code on your runner. |
431
- | **Private** CI | the org's `[self-hosted, ...]` runner **where one exists**; `ubuntu-latest` otherwise | Immune to billing, persistent tool caches, local network. Runners are registered per-org — one org's runner serves nothing in another org. Register a runner for an org when its billing or scale makes it worth it, not preemptively. |
432
- | **Private** deploy | its own runner label | Deploys must never queue behind CI jobs. |
453
+ | **Private** CI | `[self-hosted, <class>]` — a job class, never a host ([CONVENTIONS.md §7, *Runner classes*](../CONVENTIONS.md#runner-classes--runs-on-names-a-job-class-never-a-host-720)) — **where the org's pool carries that class online**; `ubuntu-latest` otherwise | Immune to billing, persistent tool caches, local network. Runners are registered per-org — one org's runner serves nothing in another org. Register a runner for an org when its billing or scale makes it worth it, not preemptively. Each template's `runs-on` `EDIT:` names the class its job takes. |
454
+ | **Private** deploy | its own restricted runner label, outside the classes | Deploys must never queue behind CI jobs. |
433
455
 
434
456
  Self-hosted job hygiene: no `sudo`, install tools into `$RUNNER_TEMP`, never
435
457
  write outside the workspace, prefer the runner's native toolchains. A shared
@@ -0,0 +1,73 @@
1
+ # CI (light lane) — CALLER of the handbook's reusable workflow (#721). Copy to .github/workflows/ci.yml
2
+ # with `colab template ci-call --dest .github/workflows/ci.yml`: it writes this repo's trunk refs and pins the call to the handbook
3
+ # release it stamps the copy with. Unlike templates/ci-<stack>.yml, nothing below the `uses:` line is
4
+ # yours to maintain — the dedupe gate, the secret scan, the quick/full split and the job-class
5
+ # `runs-on` live once, in .github/workflows/ci-light.yml of the handbook, and a release moves them.
6
+ #
7
+ # EDIT POINTS are marked `# EDIT:` — the `with:` block is the only real one.
8
+ #
9
+ # Kept HERE because a called workflow cannot declare them (CONVENTIONS.md §7, "One verdict per tree"):
10
+ # - the triggers: every branch (#384 — a candidate gets a run of its own before the merge; '**'
11
+ # also covers `ship-batch/**`), no `pull_request` beside push (#512), and workflow_dispatch (the
12
+ # release workflow dispatches CI on a promotion its token cannot trigger, #440);
13
+ # - concurrency: one live run per branch, a trunk run never cancelled and in a group of its own (#512).
14
+ # Its trunk refs and the `trunk-branches` input name the same branches — `colab template` writes both.
15
+ name: CI
16
+
17
+ on:
18
+ push:
19
+ branches: ['**']
20
+ workflow_dispatch:
21
+
22
+ concurrency:
23
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
24
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
25
+
26
+ # The called jobs can only narrow these: the gate lists this workflow's runs and reads git objects.
27
+ permissions:
28
+ actions: read
29
+ contents: read
30
+
31
+ jobs:
32
+ ci:
33
+ # Pinned to a handbook release, never a branch: a caller tracking `main` would take every gate
34
+ # change the moment it merges there, untested against this repo. Move the tag deliberately
35
+ # (`colab update` refreshes a pristine copy to the current release).
36
+ uses: futurelastic/colab-handbook/.github/workflows/ci-light.yml@HANDBOOK_TAG
37
+ with:
38
+ trunk-branches: '["main","dev"]'
39
+ # EDIT: one stack — keep the lines for yours, delete the rest. Versions are resolved from
40
+ # .github/project.yml, then the manifest (.nvmrc / engines.node, .python-version /
41
+ # requires-python, composer.json require.php); none declared fails the job, never a default.
42
+ #
43
+ # Node:
44
+ toolchain: node
45
+ install: auto # npm ci / pnpm install --frozen-lockfile, from the lockfile
46
+ quick: npm run --if-present typecheck && npm run --if-present lint
47
+ full: npm test --if-present && npm run --if-present build
48
+ #
49
+ # Python:
50
+ # toolchain: python
51
+ # install: auto # pip install -e . (or -r requirements.txt), then requirements-dev.txt
52
+ # quick: python -m ruff check . && python -m mypy src
53
+ # full: python -m pytest -q -m "not heavy" || [ $? -eq 5 ]
54
+ #
55
+ # Laravel (PHP + Vite):
56
+ # toolchain: php,node
57
+ # install: auto # composer install, then npm ci
58
+ # quick: vendor/bin/pint --test
59
+ # full: cp .env.example .env && php artisan key:generate && npm run build && php artisan migrate --force && vendor/bin/pest --ci --exclude-group=heavy
60
+ #
61
+ # EDIT: self-hosted runners — `classes` runs each job on ["self-hosted", <class>]: `trunk` on a
62
+ # trunk ref, else `quick` or `full` (CONVENTIONS.md §7, "Runner classes"). A public repo keeps
63
+ # the default, ubuntu-latest. A bare label or a JSON label list also works.
64
+ # runs-on: classes
65
+ # runner-lane: my-repo-lane # only for a capped lane (rule 3)
66
+ #
67
+ # EDIT: name your trunk-only jobs below (deploy, publish) when they sit outside the gate (#717).
68
+ # trunk-only-jobs: Deploy
69
+
70
+ # Your own jobs go here, beside the call. Behind the gate (they skip when the tree already passed):
71
+ # needs: ci
72
+ # if: ${{ !cancelled() && needs.ci.outputs.tested != 'true' }}
73
+ # Trunk-only and ungated: no `if:` on the guard, and list the job's name in `trunk-only-jobs` above.
@@ -64,7 +64,7 @@ jobs:
64
64
  # that concludes `success` when the nightly skips: a run whose jobs all skip reads as not-green.
65
65
  plan:
66
66
  name: What to test
67
- runs-on: ubuntu-latest # EDIT: needs `gh` (GitHub-hosted images have it).
67
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class, never a host (CONVENTIONS.md §7, "Runner classes"); it needs `gh`.
68
68
  timeout-minutes: 5
69
69
  permissions:
70
70
  actions: read
@@ -129,7 +129,7 @@ jobs:
129
129
  name: Full suite @ ${{ needs.plan.outputs.sha }}
130
130
  needs: plan
131
131
  if: ${{ needs.plan.outputs.run == 'true' }}
132
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
132
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: e2e (service containers), browser (browser-driven), else trunk (CONVENTIONS.md §7, "Runner classes").
133
133
  timeout-minutes: 120 # EDIT: well above YOUR heavy p99; the default is 360.
134
134
  permissions:
135
135
  contents: read
@@ -357,7 +357,7 @@ jobs:
357
357
  name: Secret scan, full history (gitleaks)
358
358
  needs: plan
359
359
  if: ${{ needs.plan.outputs.run == 'true' }}
360
- runs-on: ubuntu-latest # EDIT: the same label as ci.yml's gitleaks job.
360
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class, never a host (CONVENTIONS.md §7, "Runner classes").
361
361
  timeout-minutes: 30 # the whole history, not a range. EDIT: the default is 360.
362
362
  permissions:
363
363
  contents: read
@@ -482,7 +482,7 @@ jobs:
482
482
  name: Report a red nightly
483
483
  needs: [plan, heavy, secrets]
484
484
  if: ${{ always() && github.event_name == 'schedule' && (needs.heavy.result == 'failure' || needs.secrets.result == 'failure') }}
485
- runs-on: ubuntu-latest # EDIT: needs `gh`.
485
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class; it needs `gh`.
486
486
  timeout-minutes: 5
487
487
  permissions:
488
488
  issues: write
@@ -57,7 +57,7 @@ on:
57
57
  # EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
58
58
  # trunk has its own lane — branch runs queue ahead of the one trunk run a merge
59
59
  # waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
60
- # runners, a runner pool, or a trunk-only label picked in `runs-on` on
60
+ # runners, a runner pool, or the `trunk` class picked in `runs-on` on
61
61
  # github.ref all have that capacity; keep '**' there. Trunk-only means the
62
62
  # branches this repo actually has — and never drop `dev` on a Tier A or C repo:
63
63
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
@@ -141,7 +141,7 @@ jobs:
141
141
  name: Already tested at this sha or tree?
142
142
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
143
143
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
144
- runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
144
+ runs-on: ubuntu-latest # EDIT: self-hosted → the class of the jobs below, never a host (CONVENTIONS.md §7, "Runner classes"); it needs `gh`.
145
145
  timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
146
146
  permissions:
147
147
  actions: read
@@ -266,7 +266,7 @@ jobs:
266
266
  name: Secret scan (gitleaks)
267
267
  needs: dedupe
268
268
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
269
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
269
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: quick on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
270
270
  timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
271
271
  steps:
272
272
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -419,7 +419,7 @@ jobs:
419
419
  name: Build (Laravel + Vite)
420
420
  needs: dedupe
421
421
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
422
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
422
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: full (quick if it keeps quick's promise) on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
423
423
  timeout-minutes: 45 # a hung build must not hold the runner for the 360-minute default (#572).
424
424
  # EDIT: measured (#572): the slowest Laravel adopter's build ran p99 20 / max 26 min. Keep this
425
425
  # well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
@@ -807,7 +807,7 @@ jobs:
807
807
  # including `dedupe`, which is skipped on every ordinary push — so the implicit
808
808
  # form would skip this job on exactly the runs it exists for (#418).
809
809
  if: ${{ !cancelled() && needs.build.result == 'success' }}
810
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
810
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: e2e (service containers) (CONVENTIONS.md §7, "Runner classes").
811
811
  timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
812
812
  # EDIT: measured (#572): p99 under 4 min / max 5 min on every adopter. Keep it well above your own p99.
813
813
  strategy:
@@ -61,7 +61,7 @@ jobs:
61
61
  # that concludes `success` when the nightly skips: a run whose jobs all skip reads as not-green.
62
62
  plan:
63
63
  name: What to test
64
- runs-on: ubuntu-latest # EDIT: needs `gh` (GitHub-hosted images have it).
64
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class, never a host (CONVENTIONS.md §7, "Runner classes"); it needs `gh`.
65
65
  timeout-minutes: 5
66
66
  permissions:
67
67
  actions: read
@@ -126,7 +126,7 @@ jobs:
126
126
  name: Full suite @ ${{ needs.plan.outputs.sha }}
127
127
  needs: plan
128
128
  if: ${{ needs.plan.outputs.run == 'true' }}
129
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
129
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: e2e (service containers), browser (browser-driven), else trunk (CONVENTIONS.md §7, "Runner classes").
130
130
  timeout-minutes: 120 # EDIT: well above YOUR heavy p99; the default is 360.
131
131
  permissions:
132
132
  contents: read
@@ -280,7 +280,7 @@ jobs:
280
280
  name: Secret scan, full history (gitleaks)
281
281
  needs: plan
282
282
  if: ${{ needs.plan.outputs.run == 'true' }}
283
- runs-on: ubuntu-latest # EDIT: the same label as ci.yml's gitleaks job.
283
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class, never a host (CONVENTIONS.md §7, "Runner classes").
284
284
  timeout-minutes: 30 # the whole history, not a range. EDIT: the default is 360.
285
285
  permissions:
286
286
  contents: read
@@ -409,7 +409,7 @@ jobs:
409
409
  name: Report a red nightly
410
410
  needs: [plan, heavy, secrets]
411
411
  if: ${{ always() && github.event_name == 'schedule' && (needs.heavy.result == 'failure' || needs.secrets.result == 'failure') }}
412
- runs-on: ubuntu-latest # EDIT: needs `gh`.
412
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class; it needs `gh`.
413
413
  timeout-minutes: 5
414
414
  permissions:
415
415
  issues: write
@@ -44,7 +44,7 @@ on:
44
44
  # EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
45
45
  # trunk has its own lane — branch runs queue ahead of the one trunk run a merge
46
46
  # waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
47
- # runners, a runner pool, or a trunk-only label picked in `runs-on` on
47
+ # runners, a runner pool, or the `trunk` class picked in `runs-on` on
48
48
  # github.ref all have that capacity; keep '**' there. Trunk-only means the
49
49
  # branches this repo actually has — and never drop `dev` on a Tier A or C repo:
50
50
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
@@ -126,7 +126,7 @@ jobs:
126
126
  name: Already tested at this sha or tree?
127
127
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
128
128
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
129
- runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
129
+ runs-on: ubuntu-latest # EDIT: self-hosted → the class of the jobs below, never a host (CONVENTIONS.md §7, "Runner classes"); it needs `gh`.
130
130
  timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
131
131
  permissions:
132
132
  actions: read
@@ -251,7 +251,7 @@ jobs:
251
251
  name: Secret scan (gitleaks)
252
252
  needs: dedupe
253
253
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
254
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
254
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: quick on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
255
255
  timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
256
256
  steps:
257
257
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -431,7 +431,7 @@ jobs:
431
431
  # workspace isn't even checked out yet at job level, so a job-level
432
432
  # hashFiles() would have been testing an empty directory even if it were
433
433
  # allowed.
434
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
434
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: full (quick if it keeps quick's promise) on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
435
435
  timeout-minutes: 60 # a hung build must not hold the runner for the 360-minute default (#572).
436
436
  # EDIT: measured (#572): the slowest Node adopter's build ran p99 37 / max 43 min. Keep this
437
437
  # well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
@@ -785,7 +785,7 @@ jobs:
785
785
  # # including `dedupe`, which is skipped on every ordinary push (#418). `roundtrip` is `on`
786
786
  # # only once ROUNDTRIP_APPLY (the workflow env, above) is set — skipped until then (#625).
787
787
  # if: ${{ !cancelled() && needs.build.result == 'success' && needs.build.outputs.roundtrip == 'on' }}
788
- # runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
788
+ # runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: e2e (service containers) (CONVENTIONS.md §7, "Runner classes").
789
789
  # timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
790
790
  # # EDIT: measured (#572): p99 under 4 min on every adopter. Keep it well above your own p99.
791
791
  # strategy:
@@ -63,7 +63,7 @@ jobs:
63
63
  # that concludes `success` when the nightly skips: a run whose jobs all skip reads as not-green.
64
64
  plan:
65
65
  name: What to test
66
- runs-on: ubuntu-latest # EDIT: needs `gh` (GitHub-hosted images have it).
66
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class, never a host (CONVENTIONS.md §7, "Runner classes"); it needs `gh`.
67
67
  timeout-minutes: 5
68
68
  permissions:
69
69
  actions: read
@@ -128,7 +128,7 @@ jobs:
128
128
  name: Full suite @ ${{ needs.plan.outputs.sha }}
129
129
  needs: plan
130
130
  if: ${{ needs.plan.outputs.run == 'true' }}
131
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
131
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: e2e (service containers), browser (browser-driven), else trunk (CONVENTIONS.md §7, "Runner classes").
132
132
  timeout-minutes: 120 # EDIT: well above YOUR heavy p99; the default is 360.
133
133
  permissions:
134
134
  contents: read
@@ -289,7 +289,7 @@ jobs:
289
289
  name: Secret scan, full history (gitleaks)
290
290
  needs: plan
291
291
  if: ${{ needs.plan.outputs.run == 'true' }}
292
- runs-on: ubuntu-latest # EDIT: the same label as ci.yml's gitleaks job.
292
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class, never a host (CONVENTIONS.md §7, "Runner classes").
293
293
  timeout-minutes: 30 # the whole history, not a range. EDIT: the default is 360.
294
294
  permissions:
295
295
  contents: read
@@ -418,7 +418,7 @@ jobs:
418
418
  name: Report a red nightly
419
419
  needs: [plan, heavy, secrets]
420
420
  if: ${{ always() && github.event_name == 'schedule' && (needs.heavy.result == 'failure' || needs.secrets.result == 'failure') }}
421
- runs-on: ubuntu-latest # EDIT: needs `gh`.
421
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class; it needs `gh`.
422
422
  timeout-minutes: 5
423
423
  permissions:
424
424
  issues: write
@@ -56,7 +56,7 @@ on:
56
56
  # EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
57
57
  # trunk has its own lane — branch runs queue ahead of the one trunk run a merge
58
58
  # waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
59
- # runners, a runner pool, or a trunk-only label picked in `runs-on` on
59
+ # runners, a runner pool, or the `trunk` class picked in `runs-on` on
60
60
  # github.ref all have that capacity; keep '**' there. Trunk-only means the
61
61
  # branches this repo actually has — and never drop `dev` on a Tier A or C repo:
62
62
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
@@ -137,7 +137,7 @@ jobs:
137
137
  name: Already tested at this sha or tree?
138
138
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
139
139
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
140
- runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
140
+ runs-on: ubuntu-latest # EDIT: self-hosted → the class of the jobs below, never a host (CONVENTIONS.md §7, "Runner classes"); it needs `gh`.
141
141
  timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
142
142
  permissions:
143
143
  actions: read
@@ -262,7 +262,7 @@ jobs:
262
262
  name: Secret scan (gitleaks)
263
263
  needs: dedupe
264
264
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
265
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
265
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: quick on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
266
266
  timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
267
267
  steps:
268
268
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -419,7 +419,7 @@ jobs:
419
419
  name: Build (Python)
420
420
  needs: dedupe
421
421
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
422
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
422
+ runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: full (quick if it keeps quick's promise) on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
423
423
  timeout-minutes: 30 # a hung build must not hold the runner for the 360-minute default (#572).
424
424
  # EDIT: NOT a measured fit (#572) — one Python adopter, whose build is a byte-compile (p99
425
425
  # under 1 min). Set it well above YOUR p99 — below it a slow but healthy suite goes red.
@@ -754,7 +754,7 @@ jobs:
754
754
  # # including `dedupe`, which is skipped on every ordinary push (#418). `roundtrip` is `on`
755
755
  # # only once ROUNDTRIP_APPLY (the workflow env, above) is set — skipped until then (#625).
756
756
  # if: ${{ !cancelled() && needs.build.result == 'success' && needs.build.outputs.roundtrip == 'on' }}
757
- # runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
757
+ # runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: e2e (service containers) (CONVENTIONS.md §7, "Runner classes").
758
758
  # timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
759
759
  # # EDIT: NOT measured for Python (#572) — ci-node's adopters ran p99 under 4 min. Keep it well above your own p99.
760
760
  # strategy:
@@ -11,6 +11,7 @@ on:
11
11
  jobs:
12
12
  instruction-files:
13
13
  uses: futurelastic/colab-handbook/.github/workflows/instruction-files.yml@main
14
- # No GitHub-hosted minutes (self-hosted-only org)? Pass your runner (#594) — a label or a JSON list:
14
+ # No GitHub-hosted minutes (self-hosted-only org)? Pass your runner (#594) — a label or a JSON list,
15
+ # naming a job class, never a host (CONVENTIONS.md §7, "Runner classes"):
15
16
  # with:
16
- # runs-on: '["self-hosted","linux"]'
17
+ # runs-on: '["self-hosted","quick"]'
@@ -221,9 +221,11 @@
221
221
  # owner's billing fails GitHub refuses a hosted job before it starts: main goes red, every landing
222
222
  # is refused until a human steps in — measured twice in a row on one adopting repo, where this was
223
223
  # the only workflow on main still on hosted runners. So:
224
- # private / internal repo `release`, `npm-record` (and `deploy`, if you enable it) run on the
225
- # SAME self-hosted label your ci.yml's trunk jobs use. The runner needs
226
- # git, node, gh and jq on its PATH (GitHub-hosted images have all four).
224
+ # private / internal repo `release` and `npm-record` run on the trunk class, `[self-hosted,
225
+ # trunk]` — the class your ci.yml's trunk jobs use (CONVENTIONS.md §7,
226
+ # "Runner classes"); `deploy`, if you enable it, on its own restricted
227
+ # deploy label. The runner needs git, node, gh and jq on its PATH
228
+ # (GitHub-hosted images have all four).
227
229
  # public repo `ubuntu-latest` is fine — hosted minutes are free there.
228
230
  # the `npm` job GitHub-hosted on every repo: npm trusted publishing requires it. It only
229
231
  # runs on a public repo (a private one is refused outright, #432), so it
@@ -359,7 +361,7 @@ jobs:
359
361
  # the whole run as `skipped` at that main sha, and `colab ship` reads any finished run that is
360
362
  # neither success nor cancelled as "not green". Re-run CI green on that sha and the skipped
361
363
  # Release (auto) row would still sit beside it, refusing every ship until main moves.
362
- # EDIT: PRIVATE repo → your ci.yml's self-hosted trunk label, e.g. [self-hosted, linux]
364
+ # EDIT: PRIVATE repo → the trunk class, [self-hosted, trunk] — a class, never a host
363
365
  # (RUNNERS, above). ubuntu-latest only on a public repo.
364
366
  runs-on: ubuntu-latest
365
367
  permissions:
@@ -107,7 +107,7 @@ jobs:
107
107
  release:
108
108
  name: Publish release
109
109
  needs: heavy
110
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
110
+ runs-on: ubuntu-latest # EDIT: self-hosted → the trunk class, never a host (CONVENTIONS.md §7, "Runner classes").
111
111
  permissions:
112
112
  # Required to create the release. Nothing else is needed — keep it minimal.
113
113
  contents: write