@futurelastic/colab-handbook 1.12.0-rc.22 → 1.12.0-rc.24
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 +51 -8
- package/package.json +1 -1
- package/templates/release-auto.yml +26 -3
- package/tools/lib/release-runner.js +125 -0
package/audit/audit.mjs
CHANGED
|
@@ -94,6 +94,7 @@ const releasePolicy = require("../tools/lib/release-policy.js");
|
|
|
94
94
|
// push-site guard in the CLI, so the audit and the tool can never disagree about what it means.
|
|
95
95
|
const ownerBranchLib = require("../tools/lib/owner-branch.js");
|
|
96
96
|
const npmGuard = require("../tools/lib/npm-publish-guard.js");
|
|
97
|
+
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
97
98
|
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
|
|
98
99
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
99
100
|
// #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
|
|
@@ -572,13 +573,20 @@ function readRemoteIssue(slug, num) {
|
|
|
572
573
|
}
|
|
573
574
|
}
|
|
574
575
|
|
|
576
|
+
// Memoized per slug: several checks read visibility (#432, #453) and one audit run must not pay
|
|
577
|
+
// one API call per check.
|
|
578
|
+
const remoteMetadataCache = new Map();
|
|
575
579
|
function readRemoteMetadata(slug) {
|
|
580
|
+
if (remoteMetadataCache.has(slug)) return remoteMetadataCache.get(slug);
|
|
581
|
+
let r;
|
|
576
582
|
try {
|
|
577
583
|
const out = runGh(["api", `repos/${slug}`]);
|
|
578
|
-
|
|
584
|
+
r = { status: "ok", data: JSON.parse(out) };
|
|
579
585
|
} catch {
|
|
580
|
-
|
|
586
|
+
r = { status: "unreadable" };
|
|
581
587
|
}
|
|
588
|
+
remoteMetadataCache.set(slug, r);
|
|
589
|
+
return r;
|
|
582
590
|
}
|
|
583
591
|
|
|
584
592
|
// github.com/owner/name, git@github.com:owner/name.git → "owner/name". Non-GitHub or
|
|
@@ -1649,8 +1657,16 @@ function auditRepo(target, ctx) {
|
|
|
1649
1657
|
checkFastRouteDeploy(src, workflows, cfg, fail);
|
|
1650
1658
|
checkDeployContainer(src, workflows, cfg, warn);
|
|
1651
1659
|
checkPrivateNpm(src, workflows, fail, warn);
|
|
1660
|
+
checkReleaseRunner(src, workflows, warn);
|
|
1652
1661
|
|
|
1653
1662
|
const runbook = cfg && "runbook" in cfg ? cfg.runbook : null;
|
|
1663
|
+
// #454: on route deploy-tag-fast the release workflow's own `deploy` job ships the final (a tag
|
|
1664
|
+
// pushed with GITHUB_TOKEN starts no `push: tags` run, so it cannot be a deploy-*.yml). A cutter
|
|
1665
|
+
// that deploys what it tagged IS the in-repo path to production — it is not an external deployer,
|
|
1666
|
+
// and owes no runbook. One whose deploy step is still the placeholder counts too: the path is in
|
|
1667
|
+
// the repo, unfinished, and checkFastRouteDeploy above already fails it by name.
|
|
1668
|
+
const fastDeployers = (fastRouteCutters({ readFile: (p) => src.readFile(p), workflows, cfg }) || {}).deploying || [];
|
|
1669
|
+
const inRepoDeploy = deployWorkflows.length > 0 || fastDeployers.length > 0;
|
|
1654
1670
|
|
|
1655
1671
|
// ---- gate contract, dispatched by axis of record (#144) ------------------
|
|
1656
1672
|
// `authority` is null only when project.yml itself did not parse (already failed above,
|
|
@@ -1671,12 +1687,14 @@ function auditRepo(target, ctx) {
|
|
|
1671
1687
|
// runbook documents that path. A deploy: tag repo whose own
|
|
1672
1688
|
// CI holds the deploy job keeps its deploy-*.yml and needs no
|
|
1673
1689
|
// runbook — the workflow already commits the answer.
|
|
1674
|
-
|
|
1690
|
+
// So does a deploy-tag-fast repo whose release workflow
|
|
1691
|
+
// deploys the final it cut (#454).
|
|
1692
|
+
const externalTagDeploy = deploy === "tag" && !inRepoDeploy;
|
|
1675
1693
|
if (deploy === "manual") {
|
|
1676
1694
|
checkRunbook(src, runbook, fail, warn, "deploy: manual");
|
|
1677
1695
|
} else if (externalTagDeploy) {
|
|
1678
1696
|
checkRunbook(src, runbook, fail, warn, "deploy: tag deployed outside CI (an external GitOps poller)");
|
|
1679
|
-
} else if (!
|
|
1697
|
+
} else if (!inRepoDeploy) {
|
|
1680
1698
|
fail("tier A but no .github/workflows/deploy-*.yml — the path to production is not in the repo (use deploy: manual + runbook: if it ships by hand, or deploy: tag + runbook: when a GitOps poller deploys the tag from outside CI)");
|
|
1681
1699
|
}
|
|
1682
1700
|
if (production === null || production === "") fail("tier A but production is null — set the live URL, or drop to tier B");
|
|
@@ -1752,7 +1770,7 @@ function auditRepo(target, ctx) {
|
|
|
1752
1770
|
// construction (CONVENTIONS.md §2: no mechanism rule applies to it, not even trunk shape).
|
|
1753
1771
|
// A `runbook`-kind entry defers to `checkRunbook` here (this file can read the repo and tell
|
|
1754
1772
|
// "missing" from "unreadable via the API"); every other entry is a ready `fail` message.
|
|
1755
|
-
const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow:
|
|
1773
|
+
const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers] };
|
|
1756
1774
|
for (const entry of evaluateExposure(exp, shapeCtx)) {
|
|
1757
1775
|
if (entry.kind === "runbook") checkRunbook(src, runbook, fail, warn, entry.why);
|
|
1758
1776
|
else fail(entry.message);
|
|
@@ -2578,18 +2596,27 @@ function checkReleaseAuto(src, workflows, cfg, warn) {
|
|
|
2578
2596
|
// release.rollback: auto is the operator's statement of that, which is why the grant is required.
|
|
2579
2597
|
const FAST_DEPLOY_CONSUMER = /outputs\.(final|deploy-tag)\b|\.final\s*\/\/|jq -r '\.final\b/;
|
|
2580
2598
|
const FAST_DEPLOY_UNEDITED = /the deploy step of release-auto\.yml was never edited/;
|
|
2581
|
-
|
|
2599
|
+
// The cutters and, of those, the ones that deploy the final the cut produced. Null when the effective
|
|
2600
|
+
// route does not finalize on a green head (not the fast route). Shared by the findings below and by
|
|
2601
|
+
// the deploy-presence rule (#454), which counts a deploying cutter as the in-repo deploy path.
|
|
2602
|
+
function fastRouteCutters({ readFile, workflows, cfg }) {
|
|
2582
2603
|
const effective = cfg ? releasePolicy.evaluateRelease(cfg).effective : null;
|
|
2583
|
-
if (!effective || effective.finalize !== "on-green-head") return
|
|
2604
|
+
if (!effective || effective.finalize !== "on-green-head") return null;
|
|
2584
2605
|
const cutters = (workflows || []).filter((wf) => {
|
|
2585
2606
|
const t = readFile(`.github/workflows/${wf}`);
|
|
2586
2607
|
return t && /\brelease\s+cut\s+--auto\b/.test(t);
|
|
2587
2608
|
});
|
|
2609
|
+
const deploying = cutters.filter((wf) => FAST_DEPLOY_CONSUMER.test(readFile(`.github/workflows/${wf}`)));
|
|
2610
|
+
return { cutters, deploying };
|
|
2611
|
+
}
|
|
2612
|
+
function fastRouteDeployFindings({ readFile, workflows, cfg }) {
|
|
2613
|
+
const found = fastRouteCutters({ readFile, workflows, cfg });
|
|
2614
|
+
if (!found) return [];
|
|
2615
|
+
const { cutters, deploying } = found;
|
|
2588
2616
|
if (!cutters.length) {
|
|
2589
2617
|
return ["route: deploy-tag-fast but no workflow runs `colab release cut --auto` — nothing tags or deploys a final; copy templates/release-auto.yml (CONVENTIONS.md §6, A final on every green head)"];
|
|
2590
2618
|
}
|
|
2591
2619
|
const out = [];
|
|
2592
|
-
const deploying = cutters.filter((wf) => FAST_DEPLOY_CONSUMER.test(readFile(`.github/workflows/${wf}`)));
|
|
2593
2620
|
if (!deploying.length) {
|
|
2594
2621
|
out.push(`route: deploy-tag-fast, but ${cutters.join(", ")} runs \`colab release cut --auto\` and deploys nothing from its result — a tag pushed with GITHUB_TOKEN starts no \`push: tags\` run, so the final would never deploy; deploy in the same run (templates/release-auto.yml, job \`deploy\`)`);
|
|
2595
2622
|
}
|
|
@@ -2651,6 +2678,22 @@ function checkPrivateNpm(src, workflows, fail, warn) {
|
|
|
2651
2678
|
for (const f of all) (f.level === "fail" ? fail : warn)(f.text);
|
|
2652
2679
|
}
|
|
2653
2680
|
|
|
2681
|
+
// ---- the release workflow runs on the repo's own runners when private (#453) -------------------
|
|
2682
|
+
// A hosted job on a private repo is billed, and a billing refusal fails the release run at trunk's
|
|
2683
|
+
// head — `colab ship` then reads trunk as red. Visibility from the GitHub API, read only when a
|
|
2684
|
+
// release workflow exists; unreadable → nothing reported (advisory, never invented).
|
|
2685
|
+
function checkReleaseRunner(src, workflows, warn) {
|
|
2686
|
+
const readFile = (p) => src.readFile(p);
|
|
2687
|
+
const hasRelease = (workflows || []).some((wf) => releaseRunner.RELEASE_AUTO_RUN.test(readFile(`.github/workflows/${wf}`) || ""));
|
|
2688
|
+
if (!hasRelease) return;
|
|
2689
|
+
const meta = src.metadata ? src.metadata() : { status: "unreadable" };
|
|
2690
|
+
let visibility = null;
|
|
2691
|
+
if (meta.status === "ok" && meta.data) {
|
|
2692
|
+
visibility = meta.data.visibility || (meta.data.private === true ? "private" : meta.data.private === false ? "public" : null);
|
|
2693
|
+
}
|
|
2694
|
+
for (const text of releaseRunner.findings({ readFile, workflows, visibility })) warn(text);
|
|
2695
|
+
}
|
|
2696
|
+
|
|
2654
2697
|
function checkRunbook(src, runbook, fail, warn, why = "deploy: manual") {
|
|
2655
2698
|
if (runbook === null || runbook === "") {
|
|
2656
2699
|
fail(`${why} requires runbook: — name the committed doc that describes how production is reached (e.g. docs/deploy.md), or nobody but you can ship`);
|
package/package.json
CHANGED
|
@@ -113,6 +113,26 @@
|
|
|
113
113
|
# `npm` job, which sets up its own Node for npm's trusted publishing (EDIT point there for
|
|
114
114
|
# a package that needs a build). The npm job needs a HANDBOOK_REF that carries #433; an
|
|
115
115
|
# older CLI gives no npm verdict and nothing is published to npm.
|
|
116
|
+
#
|
|
117
|
+
# RUNNERS — ON A PRIVATE REPO, YOUR OWN (#453). This workflow fires on every green CI run on main,
|
|
118
|
+
# so any of its jobs failing is a failed run at main's head, and `colab ship` reads that as main
|
|
119
|
+
# not green. On a PRIVATE (or internal) repo GitHub-hosted minutes are billed, and when the
|
|
120
|
+
# owner's billing fails GitHub refuses a hosted job before it starts: main goes red, every landing
|
|
121
|
+
# is refused until a human steps in — measured twice in a row on one adopting repo, where this was
|
|
122
|
+
# the only workflow on main still on hosted runners. So:
|
|
123
|
+
# private / internal repo `release`, `npm-record` (and `deploy`, if you enable it) run on the
|
|
124
|
+
# SAME self-hosted label your ci.yml's trunk jobs use. The runner needs
|
|
125
|
+
# git, node, gh and jq on its PATH (GitHub-hosted images have all four).
|
|
126
|
+
# public repo `ubuntu-latest` is fine — hosted minutes are free there.
|
|
127
|
+
# the `npm` job GitHub-hosted on every repo: npm trusted publishing requires it. It only
|
|
128
|
+
# runs on a public repo (a private one is refused outright, #432), so it
|
|
129
|
+
# is never billed.
|
|
130
|
+
# The trade-off, stated: a self-hosted release job queues behind your own runners, and an offline
|
|
131
|
+
# pool delays a candidate — it never paints main red the way a refused hosted job does. The label
|
|
132
|
+
# is a literal EDIT point, not an expression keyed on visibility: `github.event.repository` is not
|
|
133
|
+
# in a scheduled run's payload, so a visibility switch would silently pick hosted on exactly the
|
|
134
|
+
# daily run. `colab audit` flags a private repo whose release workflow still runs hosted, naming
|
|
135
|
+
# the label your other workflows already use.
|
|
116
136
|
|
|
117
137
|
name: Release (auto)
|
|
118
138
|
|
|
@@ -156,7 +176,9 @@ jobs:
|
|
|
156
176
|
# the whole run as `skipped` at that main sha, and `colab ship` reads any finished run that is
|
|
157
177
|
# neither success nor cancelled as "not green". Re-run CI green on that sha and the skipped
|
|
158
178
|
# Release (auto) row would still sit beside it, refusing every ship until main moves.
|
|
159
|
-
|
|
179
|
+
# EDIT: PRIVATE repo → your ci.yml's self-hosted trunk label, e.g. [self-hosted, linux]
|
|
180
|
+
# (RUNNERS, above). ubuntu-latest only on a public repo.
|
|
181
|
+
runs-on: ubuntu-latest
|
|
160
182
|
permissions:
|
|
161
183
|
contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
|
|
162
184
|
issues: write # finalize opens / comments on / closes the "release: vX.Y.Z" tracking issue
|
|
@@ -484,7 +506,8 @@ jobs:
|
|
|
484
506
|
name: Record the npm outcome on the Release
|
|
485
507
|
needs: [release, npm]
|
|
486
508
|
if: always() && needs.release.outputs.npm == 'true'
|
|
487
|
-
|
|
509
|
+
# EDIT: the same label as `release` above — PRIVATE repo → self-hosted (RUNNERS, above).
|
|
510
|
+
runs-on: ubuntu-latest
|
|
488
511
|
permissions:
|
|
489
512
|
contents: write # edit the Release notes
|
|
490
513
|
env:
|
|
@@ -533,7 +556,7 @@ jobs:
|
|
|
533
556
|
name: Deploy the final (deploy-tag-fast)
|
|
534
557
|
needs: release
|
|
535
558
|
if: needs.release.outputs.deploy-tag != ''
|
|
536
|
-
runs-on: ubuntu-latest # EDIT: the runner your deploy needs
|
|
559
|
+
runs-on: ubuntu-latest # EDIT: the runner your deploy needs — self-hosted on a PRIVATE repo (RUNNERS, above).
|
|
537
560
|
environment: production # EDIT: the GitHub environment holding your deploy secrets, or remove.
|
|
538
561
|
permissions:
|
|
539
562
|
contents: read # check out the tag
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* The release workflow on a private repo runs on the repo's own runners (#453).
|
|
4
|
+
*
|
|
5
|
+
* On a PRIVATE (or internal) repository GitHub-hosted minutes are billed, and when the
|
|
6
|
+
* owner's billing fails GitHub refuses a hosted job before it starts. The release workflow
|
|
7
|
+
* (templates/release-auto.yml, or anything running `colab release cut|finalize --auto`) fires
|
|
8
|
+
* on every green trunk run, so a refused hosted job is a failed run at trunk's head — and
|
|
9
|
+
* `colab ship` reads that as "trunk not green" and refuses every landing until a human
|
|
10
|
+
* intervenes. Measured: two consecutive trunk-red events on one adopting repo, the release
|
|
11
|
+
* workflow being the only one on trunk still on hosted runners.
|
|
12
|
+
*
|
|
13
|
+
* The one job exempt is the one that publishes to npm: npm trusted publishing does not support
|
|
14
|
+
* self-hosted runners, and a private repo never publishes to public npm anyway (#432).
|
|
15
|
+
*
|
|
16
|
+
* Pure: takes a reader, the workflow list and the visibility the caller read from the forge
|
|
17
|
+
* (never a local guess). Unknown visibility → no finding (under-report, never invent).
|
|
18
|
+
*
|
|
19
|
+
* jobRunners(text) -> [{ job, runsOn, line, hosted, publishesNpm }]
|
|
20
|
+
* findings(...) -> string[] advisories, one per offending job
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const RELEASE_AUTO_RUN = /\brelease\s+(cut|finalize)\s+--auto\b/;
|
|
24
|
+
const HOSTED_LABEL = /^(ubuntu|windows|macos)-[\w.-]+$/i;
|
|
25
|
+
const NPM_PUBLISH = /(^|[\s;&|(])(npm|pnpm|bun|yarn(\s+npm)?)\s+publish\b/;
|
|
26
|
+
|
|
27
|
+
function stripComment(line) {
|
|
28
|
+
return line.replace(/(^|\s)#.*$/, '');
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function unquote(s) {
|
|
32
|
+
return s.trim().replace(/^['"]|['"]$/g, '');
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* The labels a `runs-on:` value names, or null when it cannot be read statically
|
|
37
|
+
* (an expression, a `group:` mapping, nothing at all).
|
|
38
|
+
*/
|
|
39
|
+
function labelsOf(value, following) {
|
|
40
|
+
const v = stripComment(value).trim();
|
|
41
|
+
if (v.includes('${{')) return null;
|
|
42
|
+
if (v.startsWith('[')) {
|
|
43
|
+
return v.replace(/^\[|\]$/g, '').split(',').map(unquote).filter(Boolean);
|
|
44
|
+
}
|
|
45
|
+
if (v) return [unquote(v)];
|
|
46
|
+
// Block list on the following lines: `- label`.
|
|
47
|
+
const out = [];
|
|
48
|
+
for (const raw of following) {
|
|
49
|
+
const l = stripComment(raw);
|
|
50
|
+
if (!l.trim()) continue;
|
|
51
|
+
const m = l.match(/^\s+-\s+(.+)$/);
|
|
52
|
+
if (!m) break;
|
|
53
|
+
if (m[1].includes('${{')) return null;
|
|
54
|
+
out.push(unquote(m[1]));
|
|
55
|
+
}
|
|
56
|
+
return out.length ? out : null;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Every job's `runs-on`, by a line scan of the `jobs:` mapping (2-space job keys). */
|
|
60
|
+
function jobRunners(text) {
|
|
61
|
+
const lines = String(text || '').split('\n');
|
|
62
|
+
const out = [];
|
|
63
|
+
let inJobs = false;
|
|
64
|
+
let current = null;
|
|
65
|
+
const flush = () => { if (current) out.push(current); current = null; };
|
|
66
|
+
lines.forEach((raw, i) => {
|
|
67
|
+
if (/^jobs:\s*(#.*)?$/.test(raw)) { inJobs = true; return; }
|
|
68
|
+
if (!inJobs) return;
|
|
69
|
+
if (/^\S/.test(raw) && !/^#/.test(raw)) { flush(); inJobs = false; return; }
|
|
70
|
+
const key = raw.match(/^ {2}([A-Za-z0-9_-]+):\s*(#.*)?$/);
|
|
71
|
+
if (key) { flush(); current = { job: key[1], runsOn: null, line: null, hosted: false, publishesNpm: false }; return; }
|
|
72
|
+
if (!current) return;
|
|
73
|
+
if (NPM_PUBLISH.test(stripComment(raw))) current.publishesNpm = true;
|
|
74
|
+
const ro = raw.match(/^ {4}runs-on:(.*)$/);
|
|
75
|
+
if (ro) {
|
|
76
|
+
const labels = labelsOf(ro[1], lines.slice(i + 1));
|
|
77
|
+
current.runsOn = labels;
|
|
78
|
+
current.line = i + 1;
|
|
79
|
+
current.hosted = !!(labels && labels.length && labels.every((l) => HOSTED_LABEL.test(l)));
|
|
80
|
+
}
|
|
81
|
+
});
|
|
82
|
+
flush();
|
|
83
|
+
return out;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** The first statically-readable self-hosted `runs-on` in the repo's other workflows, as written. */
|
|
87
|
+
function selfHostedLabel(workflows, readFile, except) {
|
|
88
|
+
for (const wf of workflows || []) {
|
|
89
|
+
if (wf === except) continue;
|
|
90
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
91
|
+
if (!text) continue;
|
|
92
|
+
for (const j of jobRunners(text)) {
|
|
93
|
+
if (j.runsOn && j.runsOn.some((l) => l === 'self-hosted')) {
|
|
94
|
+
return { wf, labels: j.runsOn };
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
return null;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function isPrivate(visibility) {
|
|
102
|
+
const v = visibility ? String(visibility).toLowerCase() : null;
|
|
103
|
+
return v === 'private' || v === 'internal';
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function findings({ readFile, workflows, visibility }) {
|
|
107
|
+
if (!isPrivate(visibility)) return [];
|
|
108
|
+
const out = [];
|
|
109
|
+
for (const wf of workflows || []) {
|
|
110
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
111
|
+
if (!text || !RELEASE_AUTO_RUN.test(text)) continue;
|
|
112
|
+
const hosted = jobRunners(text).filter((j) => j.hosted && !j.publishesNpm);
|
|
113
|
+
if (!hosted.length) continue;
|
|
114
|
+
const own = selfHostedLabel(workflows, readFile, wf);
|
|
115
|
+
const hint = own
|
|
116
|
+
? `use the label your ${own.wf} already runs on: runs-on: [${own.labels.join(', ')}]`
|
|
117
|
+
: 'use your self-hosted trunk runner label';
|
|
118
|
+
for (const j of hosted) {
|
|
119
|
+
out.push(`${wf} job \`${j.job}\` runs on GitHub-hosted (${j.runsOn.join(', ')}, line ${j.line}) on a ${String(visibility).toLowerCase()} repo — hosted minutes are billed here, and a billing refusal fails this run at trunk's head, which turns trunk red for \`colab ship\`; ${hint} (templates/release-auto.yml, RUNNERS)`);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
return out;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
module.exports = { jobRunners, selfHostedLabel, findings, isPrivate, RELEASE_AUTO_RUN };
|