@futurelastic/colab-handbook 1.20.4-rc.9 → 1.21.0-rc.10
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 +102 -1
- package/package.json +1 -1
- package/templates/README.md +65 -10
- package/templates/ci-call.yml +75 -0
- package/templates/ci-laravel.yml +128 -682
- package/templates/ci-node.yml +88 -676
- package/templates/ci-python.yml +104 -644
- package/templates/release-auto.yml +148 -50
- package/tools/colab +431 -74
- package/tools/lib/blocked-by.js +3 -1
- package/tools/lib/checklist.js +12 -3
- package/tools/lib/ci-cure.js +47 -1
- package/tools/lib/ci-grant.js +61 -11
- package/tools/lib/ci-wait.js +18 -2
- package/tools/lib/codec/labels.d.ts +1 -1
- package/tools/lib/codec/labels.js +5 -2
- package/tools/lib/config-set.js +1 -1
- package/tools/lib/gate-drift.js +112 -0
- package/tools/lib/git.js +75 -2
- package/tools/lib/release-only.js +182 -0
- package/tools/lib/stale-base.js +15 -2
- package/tools/lib/stamp.js +15 -9
- package/tools/lib/template-roundtrip.js +7 -4
- package/tools/lib/template-trunk.js +45 -4
- package/tools/lib/trust-humans.js +46 -1
- 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
|
|
@@ -147,6 +149,8 @@ const treeGreenLib = require("../tools/lib/tree-green.js");
|
|
|
147
149
|
const docsOnlyLib = require("../tools/lib/docs-only.js");
|
|
148
150
|
// #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
|
|
149
151
|
const verifyRunsLib = require("../tools/lib/verify-runs.js");
|
|
152
|
+
// #736: `release-only-checks:` — read through the same module ship's release-only door uses.
|
|
153
|
+
const releaseOnlyLib = require("../tools/lib/release-only.js");
|
|
150
154
|
// #410: the optional `gate:` block — read through the same module the skills name.
|
|
151
155
|
const gateLib = require("../tools/lib/gate.js");
|
|
152
156
|
// #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
|
|
@@ -266,7 +270,11 @@ function parseScalarValue(raw) {
|
|
|
266
270
|
return val;
|
|
267
271
|
}
|
|
268
272
|
|
|
269
|
-
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630
|
|
273
|
+
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention", "release-only-checks"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630 · release-only-checks: #736
|
|
274
|
+
// #736: the one map whose KEYS are free text — a check's display name ("Install smoke", "CI / install (*)"),
|
|
275
|
+
// optionally quoted, never containing ":" — and whose every value is an INLINE list of paths. Still one
|
|
276
|
+
// level, still no block list: any other line under it is a finding.
|
|
277
|
+
const FREE_KEY_MAP_KEYS = new Set(["release-only-checks"]);
|
|
270
278
|
// The one map whose pairs may hold an INLINE list (`coupled: [a, b]`) — still one level, still no block list (#630).
|
|
271
279
|
const LIST_IN_MAP_KEYS = new Set(["contention"]);
|
|
272
280
|
// A key whose empty value may open EITHER a block list or a one-level map: `migrations:` is a list of
|
|
@@ -293,6 +301,19 @@ function parseFlatYaml(text) {
|
|
|
293
301
|
out[listKey].push(parseScalarValue(item[1]));
|
|
294
302
|
return;
|
|
295
303
|
}
|
|
304
|
+
if (mapKey !== null && FREE_KEY_MAP_KEYS.has(mapKey) && !item) {
|
|
305
|
+
const fp = line.match(/^(\s+)("[^"]+"|'[^']+'|[^\s#"'][^:#]*?)\s*:\s*(.*)$/);
|
|
306
|
+
const fpVal = fp ? fp[3].replace(/\s+#.*$/, "").trim() : "";
|
|
307
|
+
if (fp && (mapIndent === null || fp[1].length === mapIndent) && /^\[.*\]$/.test(fpVal)) {
|
|
308
|
+
if (mapIndent === null) mapIndent = fp[1].length;
|
|
309
|
+
if (out[mapKey] === null || typeof out[mapKey] !== "object") out[mapKey] = {};
|
|
310
|
+
const inner = fpVal.slice(1, -1).trim();
|
|
311
|
+
out[mapKey][fp[2]] = inner === "" ? [] : inner.split(",").map((x) => parseScalarValue(x));
|
|
312
|
+
return;
|
|
313
|
+
}
|
|
314
|
+
problems.push(`line ${idx + 1}: "${mapKey}:" takes one level of "<check name>: [paths]" pairs, each list inline — nothing deeper, no block list`);
|
|
315
|
+
return;
|
|
316
|
+
}
|
|
296
317
|
const pair = line.match(/^(\s+)([A-Za-z0-9_.-]+)\s*:\s*(.*)$/);
|
|
297
318
|
if (mapKey !== null && pair && !item) {
|
|
298
319
|
const [, indent, sub, subRaw] = pair;
|
|
@@ -584,6 +605,13 @@ function listRemoteDir(slug, path) {
|
|
|
584
605
|
}
|
|
585
606
|
}
|
|
586
607
|
|
|
608
|
+
// #721: one GitHub REST read, parsed — null when it could not be read (offline, no auth, an API error).
|
|
609
|
+
function readRemoteJson(slug, path) {
|
|
610
|
+
const r = remoteCache.get(slug, `repos/${slug}/${path}`);
|
|
611
|
+
if (r.status !== "ok") return null;
|
|
612
|
+
try { return JSON.parse(r.text); } catch { return null; }
|
|
613
|
+
}
|
|
614
|
+
|
|
587
615
|
function listRemoteBranches(slug) {
|
|
588
616
|
const r = remoteCache.get(slug, `repos/${slug}/branches`, { paginate: true });
|
|
589
617
|
return r.status === "ok" ? r.items.map((b) => String(b.name)) : null; // null = could not determine, distinct from "no branches"
|
|
@@ -872,6 +900,12 @@ function makeSource(target) {
|
|
|
872
900
|
const slug = url ? githubSlugFromRemote(url) : null;
|
|
873
901
|
return slug ? readRemoteIssue(slug, num) : null;
|
|
874
902
|
},
|
|
903
|
+
// #721: a REST read under repos/<slug>/ on the same resolved remote; null = unreadable.
|
|
904
|
+
ghApi: (p) => {
|
|
905
|
+
const url = gitRemote.remoteUrl(root);
|
|
906
|
+
const slug = url ? githubSlugFromRemote(url) : null;
|
|
907
|
+
return slug ? readRemoteJson(slug, p) : null;
|
|
908
|
+
},
|
|
875
909
|
// Same remote-slug resolution as labels() above, one API call, and only when the
|
|
876
910
|
// identity scan was explicitly asked for — see readRemoteMetadata for the contract.
|
|
877
911
|
// An unresolvable remote is its own status, not "no-remote": the scan was asked for
|
|
@@ -930,6 +964,7 @@ function makeSource(target) {
|
|
|
930
964
|
isLinkedWorktree: () => false,
|
|
931
965
|
labels: () => listRemoteLabels(target.slug),
|
|
932
966
|
issue: (num) => readRemoteIssue(target.slug, num),
|
|
967
|
+
ghApi: (p) => readRemoteJson(target.slug, p),
|
|
933
968
|
// Anchor-link check is local-only by design (#158) — enumerating markdown remotely
|
|
934
969
|
// would be N `gh api` calls per repo across a fleet sweep. Empty list = the check
|
|
935
970
|
// scans nothing and emits nothing for a remote source, matching checkRunbook's
|
|
@@ -1584,6 +1619,18 @@ function auditRepoInner(target, ctx) {
|
|
|
1584
1619
|
for (const why of vp.problems) fail(why);
|
|
1585
1620
|
}
|
|
1586
1621
|
|
|
1622
|
+
// ---- release-only-checks (#736) ---------------------------------------------
|
|
1623
|
+
// Checks that matter only to a release, each next to the paths it covers: ship's per-branch
|
|
1624
|
+
// release-only door lets a branch past a trunk red only on them when it touches none of those
|
|
1625
|
+
// paths. An invalid declaration fails: the reader ignores the whole key, so it exempts nothing.
|
|
1626
|
+
{
|
|
1627
|
+
const ro = releaseOnlyLib.parseReleaseOnly(cfg);
|
|
1628
|
+
info.releaseOnlyChecks = ro.declared && ro.valid
|
|
1629
|
+
? ro.checks.map((c) => ({ check: c.key, workflow: c.workflow, job: c.job, paths: c.paths }))
|
|
1630
|
+
: null;
|
|
1631
|
+
for (const why of ro.problems) fail(why);
|
|
1632
|
+
}
|
|
1633
|
+
|
|
1587
1634
|
// ---- gate (#410) ----------------------------------------------------------
|
|
1588
1635
|
// Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
|
|
1589
1636
|
// parseGate is the one reading. An invalid block fails: the reader falls back to the local full
|
|
@@ -2187,6 +2234,8 @@ function auditRepoInner(target, ctx) {
|
|
|
2187
2234
|
info.predatesAxes = [];
|
|
2188
2235
|
info.suggestions = [];
|
|
2189
2236
|
const suggest = (t) => info.suggestions.push(t);
|
|
2237
|
+
// #721: the CI dedupe gate maintained once — a copy of it, or a gate that never skips, is drift.
|
|
2238
|
+
checkGateDrift(src, workflows, cfg?.trunk ?? null, warn, { self: isSelf, suggest });
|
|
2190
2239
|
if (integrationSuggestion) suggest(integrationSuggestion); // #610
|
|
2191
2240
|
if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw, suggest });
|
|
2192
2241
|
|
|
@@ -2853,6 +2902,58 @@ function checkInstructionFilesCaller(src, workflows, trunk, warn) {
|
|
|
2853
2902
|
for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
|
|
2854
2903
|
}
|
|
2855
2904
|
|
|
2905
|
+
// ---- CI gate drift (#721) ----------------------------------------------------
|
|
2906
|
+
// The dedupe gate lives once, in the handbook's reusable workflow (.github/workflows/ci-light.yml).
|
|
2907
|
+
// Two readings, both warn (drift, not customisation — the repo still owns its files):
|
|
2908
|
+
// 1. a workflow carrying its own copy of the gate instead of calling ci-light.yml — static, always;
|
|
2909
|
+
// 2. a guarded workflow whose last N trunk push runs never skipped although one landed a tree another
|
|
2910
|
+
// ref had already passed green — read from run history, so only where GitHub can be read.
|
|
2911
|
+
// The handbook itself is the source: its ci.yml and ci-light.yml carry the gate by design, so the
|
|
2912
|
+
// static reading is off here (self-audit); the history reading still runs.
|
|
2913
|
+
// Reading 1 is a warn only once the handbook's latest release tag carries ci-light.yml: before that
|
|
2914
|
+
// there is nothing to switch TO (a caller pins a tag), so it is a suggestion — the #607 posture for a
|
|
2915
|
+
// CI copy — and it turns into drift by itself the day a release ships the workflow.
|
|
2916
|
+
let reusableReleasedMemo;
|
|
2917
|
+
function reusableReleased() {
|
|
2918
|
+
if (reusableReleasedMemo !== undefined) return reusableReleasedMemo;
|
|
2919
|
+
const hb = handbookInfo(HANDBOOK_ROOT);
|
|
2920
|
+
reusableReleasedMemo = false;
|
|
2921
|
+
if (hb.hasGit && !hb.untagged) {
|
|
2922
|
+
try {
|
|
2923
|
+
execFileSync("git", ["-C", HANDBOOK_ROOT, "cat-file", "-e", `${hb.version}:${gateDrift.REUSABLE_PATH}`], { stdio: "ignore" });
|
|
2924
|
+
reusableReleasedMemo = hb.version;
|
|
2925
|
+
} catch { reusableReleasedMemo = false; }
|
|
2926
|
+
}
|
|
2927
|
+
return reusableReleasedMemo;
|
|
2928
|
+
}
|
|
2929
|
+
function checkGateDrift(src, workflows, trunk, warn, { self = false, suggest = () => {} } = {}) {
|
|
2930
|
+
const { callers, copies } = gateDrift.copiedGates({ readFile: (p) => src.readFile(p), workflows });
|
|
2931
|
+
if (!self && copies.length) {
|
|
2932
|
+
const released = reusableReleased();
|
|
2933
|
+
for (const wf of copies) {
|
|
2934
|
+
if (released) warn(gateDrift.copiedGateText(wf));
|
|
2935
|
+
else suggest(`${wf}: ${gateDrift.copiedGateText(wf)} — a suggestion until a handbook release tag carries ${gateDrift.REUSABLE_PATH}`);
|
|
2936
|
+
}
|
|
2937
|
+
}
|
|
2938
|
+
if (!trunk || typeof src.ghApi !== "function") return;
|
|
2939
|
+
for (const wf of [...callers, ...copies]) {
|
|
2940
|
+
if (self && wf === "ci-light.yml") continue; // the callee: its runs are its callers'
|
|
2941
|
+
const q = (p) => src.ghApi(`actions/workflows/${encodeURIComponent(wf)}/${p}`);
|
|
2942
|
+
const trunkList = q(`runs?branch=${encodeURIComponent(trunk)}&event=push&status=completed&per_page=${gateDrift.RECENT_TRUNK_RUNS}`);
|
|
2943
|
+
if (!trunkList || !Array.isArray(trunkList.workflow_runs)) continue; // unreadable or offline — say nothing
|
|
2944
|
+
const greenList = q("runs?event=push&status=success&per_page=50"); // the guard's own window (#493)
|
|
2945
|
+
if (!greenList || !Array.isArray(greenList.workflow_runs)) continue;
|
|
2946
|
+
const tree = (r) => (r.head_commit && r.head_commit.tree_id) || null;
|
|
2947
|
+
const trunkRuns = trunkList.workflow_runs.slice(0, gateDrift.RECENT_TRUNK_RUNS).map((r) => {
|
|
2948
|
+
const j = src.ghApi(`actions/runs/${r.id}/jobs?per_page=100`);
|
|
2949
|
+
return { id: r.id, tree: tree(r), created: r.created_at, jobs: j && Array.isArray(j.jobs) ? j.jobs : null };
|
|
2950
|
+
});
|
|
2951
|
+
const greenRuns = greenList.workflow_runs.map((r) => ({ id: r.id, branch: r.head_branch, tree: tree(r), created: r.created_at }));
|
|
2952
|
+
const r = gateDrift.gateNeverSkips({ trunkRuns, greenRuns, trunk });
|
|
2953
|
+
if (r.verdict === "drift") warn(gateDrift.inertGateText(wf, r));
|
|
2954
|
+
}
|
|
2955
|
+
}
|
|
2956
|
+
|
|
2856
2957
|
// ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
|
|
2857
2958
|
// The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
|
|
2858
2959
|
// same finding; this maps its severity onto the audit's fail/warn.
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -2,10 +2,12 @@
|
|
|
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). The light CI templates are the other:
|
|
8
|
+
> `ci-node.yml`, `ci-python.yml`, `ci-laravel.yml` (since #724) and the generic `ci-call.yml` call the
|
|
9
|
+
> reusable light lane `.github/workflows/ci-light.yml`, pinned to a release tag (#721 — see
|
|
10
|
+
> *The reusable light lane* below). Every other file here is copied, not called. (`dist-refs.yml` is a
|
|
9
11
|
> `workflow_call` workflow, but its caller is your own release workflow, in the same repo, via
|
|
10
12
|
> `uses: ./.github/workflows/dist-refs.yml` — the file still lives, in full, where it runs.) An earlier version of this
|
|
11
13
|
> handbook told repos to call shared workflows; that was reversed. Every other workflow now
|
|
@@ -102,12 +104,13 @@ check that reads one of these files is that tool's behaviour, documented with th
|
|
|
102
104
|
|
|
103
105
|
| File | Copy to | For | Notes |
|
|
104
106
|
|---|---|---|---|
|
|
105
|
-
| `ci-
|
|
106
|
-
| `ci-
|
|
107
|
-
| `ci-
|
|
108
|
-
| `ci-python.yml` | `.github/workflows/ci.yml` |
|
|
107
|
+
| `ci-call.yml` | `.github/workflows/ci.yml` | The generic caller: a hybrid repo, or a stack with no `ci-<stack>.yml` of its own (#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. |
|
|
108
|
+
| `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | A **caller** of `ci-light.yml` (#724), its `with:` filled in for Node: typecheck/lint in `quick`, `npm test` and the build in `full`, each only if `package.json` declares it. The call resolves Node from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. Opt-in `Migration round-trip` job beside the call — `--roundtrip` writes it live, see *Migration round-trip* below. |
|
|
109
|
+
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | A **caller** of `ci-light.yml` (#724). Same resolution for **both** PHP and Node. Its `full` script carries the test tier (`RUN_TESTS`), the sqlite bootstrap + explicit wayfinder step and the Vite build; beside the call, 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. |
|
|
110
|
+
| `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. **Still a copy** (#724 kept it one: it runs nightly and on candidates, never per merge, so it is not what drifted, and its plan gate is per-repo). Its toolchain resolution follows the same precedence as the reusable light lane's, and the `secrets` job's gitleaks install and `GITLEAKS_VERSION` follow its `gitleaks` job — keep them in step. `TRUNK` is an edit point. |
|
|
111
|
+
| `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | A **caller** of `ci-light.yml` (#724): byte-compile, ruff and mypy in `quick`, pytest in `full`, each only if installed. The call resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: `toolchain: python,node` in the same call — see the template header. Opt-in `Migration round-trip` job, as in `ci-node.yml`. |
|
|
109
112
|
| `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
|
|
110
|
-
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547)
|
|
113
|
+
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547). A first job, `decide`, skips the heavy job on a run with nothing to do: a red CI run, a CI run at a sha that already carries its tag, or an hourly run with nothing to retry (#735). It uses a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
111
114
|
| `forgejo-release-auto.yml` | `.forgejo/workflows/release-auto.yml` | A repo hosted on **Forgejo** (or Gitea) whose §6 release route cuts candidates, with the forge named in the machine config's `forges` (#678) | The Forgejo dialect of `release-auto.yml` (#681). It has no `workflow_run`: the job you append to your CI (in its header) dispatches it when CI ends green, with `source=ci-completed` and the sha it tested. It waits for CI at that sha (`colab ci-wait`), then runs `colab release cut --auto --sha`, which tags the candidate and publishes its pre-release through the forge's API. No `permissions:` blocks, full-URL `uses:`, the runner label from the `RELEASE_RUNNER` variable, verdicts printed to the log (Forgejo drops the step summary), no `jq`. A refusal stays green. No verdict is a red run. **No finalize step**: on a forge a final is a human's `release finalize` under the human bar, which also publishes the final's release, so no tag-push workflow is needed. Keep its `name:` equal to the file's base name, because the CLI drops its own statuses by that name. |
|
|
112
115
|
| `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
|
|
113
116
|
| `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
|
|
@@ -176,11 +179,63 @@ The rule all of this keeps: [one verdict per tree](../CONVENTIONS.md#one-verdict
|
|
|
176
179
|
Opt out with `tree-reuse: off` (`project.schema.md`) when trunk's run proves something a branch
|
|
177
180
|
run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned runner images.
|
|
178
181
|
|
|
182
|
+
### The reusable light lane — calling instead of copying (#721)
|
|
183
|
+
|
|
184
|
+
The guard above drifted copy by copy: measured across adopters (2026-11-09 → 11-11), missing in six
|
|
185
|
+
repositories and present but never skipping in three, and #717's fix reached a copy only through a manual
|
|
186
|
+
sync. `.github/workflows/ci-light.yml` carries the same guard, the same secret scan and the descriptor check
|
|
187
|
+
once, for every caller; `ci-node.yml`, `ci-python.yml` and `ci-laravel.yml` are its callers since #724, and
|
|
188
|
+
`ci-call.yml` is the generic one. What changes for you:
|
|
189
|
+
|
|
190
|
+
- **Only the caller is yours**: the triggers and `concurrency` (a called workflow cannot own either), the
|
|
191
|
+
`with:` block, and your own jobs beside the call. A job behind the gate reads `needs: ci` +
|
|
192
|
+
`if: ${{ !cancelled() && needs.ci.result == 'success' && needs.ci.outputs.tested != 'true' }}` (the
|
|
193
|
+
result term keeps it off a red call); a trunk-only job outside it is named in `trunk-only-jobs` (#717).
|
|
194
|
+
- **Pinned to a release tag, never `main`.** `colab template ci-<stack>` writes the version it stamps the
|
|
195
|
+
copy with; `colab update` moves a pristine copy's stamp and pin together — including a pristine full copy
|
|
196
|
+
from before #724, which it moves onto the caller. **Until a final release carries `ci-light.yml`** (the
|
|
197
|
+
stamp is always the latest final, never a candidate, #334), `colab template ci-<stack>` and `colab update`
|
|
198
|
+
write that release's *own* template — a full copy that runs today — never a caller pinned at a release
|
|
199
|
+
that cannot run it (#724).
|
|
200
|
+
- **The quick/full split is two jobs**: `quick` (descriptor check, lint, types, unit — the `quick` class)
|
|
201
|
+
and `full` (the light suite, the build — the `full` class); both run on every push the gate does not skip,
|
|
202
|
+
and both take the `trunk` class on a trunk ref under `runs-on: classes`.
|
|
203
|
+
- **On a non-trunk ref, full starts only after quick passed** (#734). Those are the refs `concurrency`
|
|
204
|
+
cancels, and a run cancelled by the next push used to have every lane running already: late cancels
|
|
205
|
+
were 8.5% of a self-hosted fleet's runner-minutes over 14 days. A trunk run is unchanged — never
|
|
206
|
+
cancelled, never delayed, full beside quick. `needs:` cannot be conditional, so the call holds the full
|
|
207
|
+
command as two jobs of one name (`full` on trunk, `full-staged` elsewhere); exactly one runs, a required
|
|
208
|
+
check by name is met by it, and the gate does not count the skipped twin as a skip (#511).
|
|
209
|
+
A red quick on a branch therefore hides that push's full failures until quick is fixed — the price of
|
|
210
|
+
not paying for a full run whose verdict is already red.
|
|
211
|
+
- **Not calling it yet?** A hand-written CI with heavy jobs (full tests, browser/e2e, desktop builds) should
|
|
212
|
+
stage them the same way: on a non-trunk ref, `needs:` the quick job and require
|
|
213
|
+
`needs.<quick>.result == 'success'`; on a trunk ref, keep them beside it. The pair, as the call writes it:
|
|
214
|
+
```yaml
|
|
215
|
+
e2e: # trunk twin — unchanged
|
|
216
|
+
needs: dedupe
|
|
217
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && contains(fromJSON('["main","dev"]'), github.ref_name) }}
|
|
218
|
+
e2e-staged: # every other ref — the ones concurrency cancels
|
|
219
|
+
name: <the same name as e2e>
|
|
220
|
+
needs: [dedupe, quick]
|
|
221
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && needs.quick.result == 'success' && !contains(fromJSON('["main","dev"]'), github.ref_name) }}
|
|
222
|
+
```
|
|
223
|
+
Give both twins one `name:` and identical steps. If your copy carries the dedupe guard, its #511 skip
|
|
224
|
+
rule must also pass over a skipped job whose name a successful job of the same run carries (the call's
|
|
225
|
+
guard does — copy that `jq`), or no branch run can be cited at the landing again.
|
|
226
|
+
- **Mid-session backup pushes start no run at all** when they go to `refs/backup/<branch>` instead of the
|
|
227
|
+
branch (CONVENTIONS.md §7, *One verdict per tree*, rule 5).
|
|
228
|
+
- **The package caches moved too**: npm, pip and Composer, each on only on a GitHub-hosted runner and with
|
|
229
|
+
its lockfile present (#571), now in the call. Laravel's PHP extensions are the `php-extensions` input.
|
|
230
|
+
- A workflow still carrying its own copy of the gate is reported as drift — a suggestion until a handbook
|
|
231
|
+
release tag carries `ci-light.yml`, a warning from then on.
|
|
232
|
+
|
|
179
233
|
### Migration round-trip — have it from the first copy
|
|
180
234
|
|
|
181
235
|
`migration-grant: reviewer` grants only where a `Migration round-trip…` job passed at the
|
|
182
236
|
shipped head (condition R, [CONVENTIONS §5](../CONVENTIONS.md#migration-exemption--a-narrow-door-through-no-new-migrations-opened-by-a-role-98-402)).
|
|
183
|
-
`ci-laravel.yml` always carries it
|
|
237
|
+
`ci-laravel.yml` always carries it, as a job beside the call (`needs: ci`, behind the gate). `ci-node.yml`
|
|
238
|
+
and `ci-python.yml` carry it as an opt-in
|
|
184
239
|
block, and **the time to opt in is the copy** (#625):
|
|
185
240
|
|
|
186
241
|
```sh
|
|
@@ -192,7 +247,7 @@ colab template ci-python --dest .github/workflows/ci.yml --roundtrip --roundtrip
|
|
|
192
247
|
that can rewrite the job grading it never passes R — so that one branch, and its migration,
|
|
193
248
|
ships on a human grant. In the commit that creates the workflows, there is no such branch.
|
|
194
249
|
- **No migrations yet?** Leave out `--roundtrip-apply`. The job is written but **skipped**
|
|
195
|
-
until `ROUNDTRIP_APPLY` (
|
|
250
|
+
until `ROUNDTRIP_APPLY` (the `roundtrip-config` job's `env`, beside the call — a job-level `if:` cannot read `env`, so that small job hands it on) is set: a skipped leg never passes
|
|
196
251
|
R, so migrations ship on a human grant, and CI stays green — a fresh repo is not held red.
|
|
197
252
|
The build job prints a warning saying so. The cost while skipped: trunk does not reuse a
|
|
198
253
|
branch's identical-tree run (#511). A green no-op job would pass R without testing
|
|
@@ -0,0 +1,75 @@
|
|
|
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. Like templates/ci-<stack>.yml (callers too since #724, each with one
|
|
4
|
+
# stack's `with:` filled in — this one is the generic caller, for a hybrid), nothing below the `uses:` line is
|
|
5
|
+
# yours to maintain — the dedupe gate, the secret scan, the quick/full split (full staged behind quick on
|
|
6
|
+
# a non-trunk ref, #734) and the job-class
|
|
7
|
+
# `runs-on` live once, in .github/workflows/ci-light.yml of the handbook, and a release moves them.
|
|
8
|
+
#
|
|
9
|
+
# EDIT POINTS are marked `# EDIT:` — the `with:` block is the only real one.
|
|
10
|
+
#
|
|
11
|
+
# Kept HERE because a called workflow cannot declare them (CONVENTIONS.md §7, "One verdict per tree"):
|
|
12
|
+
# - the triggers: every branch (#384 — a candidate gets a run of its own before the merge; '**'
|
|
13
|
+
# also covers `ship-batch/**`), no `pull_request` beside push (#512), and workflow_dispatch (the
|
|
14
|
+
# release workflow dispatches CI on a promotion its token cannot trigger, #440);
|
|
15
|
+
# - concurrency: one live run per branch, a trunk run never cancelled and in a group of its own (#512).
|
|
16
|
+
# Its trunk refs and the `trunk-branches` input name the same branches — `colab template` writes both.
|
|
17
|
+
name: CI
|
|
18
|
+
|
|
19
|
+
on:
|
|
20
|
+
push:
|
|
21
|
+
branches: ['**']
|
|
22
|
+
workflow_dispatch:
|
|
23
|
+
|
|
24
|
+
concurrency:
|
|
25
|
+
group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
|
|
26
|
+
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
|
|
27
|
+
|
|
28
|
+
# The called jobs can only narrow these: the gate lists this workflow's runs and reads git objects.
|
|
29
|
+
permissions:
|
|
30
|
+
actions: read
|
|
31
|
+
contents: read
|
|
32
|
+
|
|
33
|
+
jobs:
|
|
34
|
+
ci:
|
|
35
|
+
# Pinned to a handbook release, never a branch: a caller tracking `main` would take every gate
|
|
36
|
+
# change the moment it merges there, untested against this repo. Move the tag deliberately
|
|
37
|
+
# (`colab update` refreshes a pristine copy to the current release).
|
|
38
|
+
uses: futurelastic/colab-handbook/.github/workflows/ci-light.yml@HANDBOOK_TAG
|
|
39
|
+
with:
|
|
40
|
+
trunk-branches: '["main","dev"]'
|
|
41
|
+
# EDIT: one stack — keep the lines for yours, delete the rest. Versions are resolved from
|
|
42
|
+
# .github/project.yml, then the manifest (.nvmrc / engines.node, .python-version /
|
|
43
|
+
# requires-python, composer.json require.php); none declared fails the job, never a default.
|
|
44
|
+
#
|
|
45
|
+
# Node:
|
|
46
|
+
toolchain: node
|
|
47
|
+
install: auto # npm ci / pnpm install --frozen-lockfile, from the lockfile
|
|
48
|
+
quick: npm run --if-present typecheck && npm run --if-present lint
|
|
49
|
+
full: npm test --if-present && npm run --if-present build
|
|
50
|
+
#
|
|
51
|
+
# Python:
|
|
52
|
+
# toolchain: python
|
|
53
|
+
# install: auto # pip install -e . (or -r requirements.txt), then requirements-dev.txt
|
|
54
|
+
# quick: python -m ruff check . && python -m mypy src
|
|
55
|
+
# full: python -m pytest -q -m "not heavy" || [ $? -eq 5 ]
|
|
56
|
+
#
|
|
57
|
+
# Laravel (PHP + Vite):
|
|
58
|
+
# toolchain: php,node
|
|
59
|
+
# install: auto # composer install, then npm ci
|
|
60
|
+
# quick: vendor/bin/pint --test
|
|
61
|
+
# full: cp .env.example .env && php artisan key:generate && npm run build && php artisan migrate --force && vendor/bin/pest --ci --exclude-group=heavy
|
|
62
|
+
#
|
|
63
|
+
# EDIT: self-hosted runners — `classes` runs each job on ["self-hosted", <class>]: `trunk` on a
|
|
64
|
+
# trunk ref, else `quick` or `full` (CONVENTIONS.md §7, "Runner classes"). A public repo keeps
|
|
65
|
+
# the default, ubuntu-latest. A bare label or a JSON label list also works.
|
|
66
|
+
# runs-on: classes
|
|
67
|
+
# runner-lane: my-repo-lane # only for a capped lane (rule 3)
|
|
68
|
+
#
|
|
69
|
+
# EDIT: name your trunk-only jobs below (deploy, publish) when they sit outside the gate (#717).
|
|
70
|
+
# trunk-only-jobs: Deploy
|
|
71
|
+
|
|
72
|
+
# Your own jobs go here, beside the call. Behind the gate (they skip when the tree already passed):
|
|
73
|
+
# needs: ci
|
|
74
|
+
# if: ${{ !cancelled() && needs.ci.result == 'success' && needs.ci.outputs.tested != 'true' }}
|
|
75
|
+
# Trunk-only and ungated: no `if:` on the guard, and list the job's name in `trunk-only-jobs` above.
|