@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 +70 -0
- package/package.json +1 -1
- package/templates/README.md +27 -5
- package/templates/ci-call.yml +73 -0
- package/templates/ci-laravel-heavy.yml +4 -4
- package/templates/ci-laravel.yml +5 -5
- package/templates/ci-node-heavy.yml +4 -4
- package/templates/ci-node.yml +5 -5
- package/templates/ci-python-heavy.yml +4 -4
- package/templates/ci-python.yml +5 -5
- package/templates/instruction-files.yml +3 -2
- package/templates/release-auto.yml +6 -4
- package/templates/release-tag.yml +1 -1
- package/tools/colab +64 -6
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/ci-wait.js +16 -2
- package/tools/lib/gate-drift.js +110 -0
- package/tools/lib/git.js +44 -1
- package/tools/lib/release-runner.js +1 -1
- package/tools/lib/stale-base.js +15 -2
- package/tools/lib/template-trunk.js +23 -4
- package/tools/lib/verify-runs.js +207 -15
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
package/templates/README.md
CHANGED
|
@@ -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
|
|
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).
|
|
8
|
-
>
|
|
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 |
|
|
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:
|
|
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
|
|
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
|
|
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
|
package/templates/ci-laravel.yml
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
package/templates/ci-node.yml
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
package/templates/ci-python.yml
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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","
|
|
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
|
|
225
|
-
#
|
|
226
|
-
#
|
|
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 →
|
|
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
|
|
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
|