@futurelastic/colab-handbook 1.12.0-rc.22 → 1.12.0-rc.23
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 +27 -2
- 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,6 +1657,7 @@ 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;
|
|
1654
1663
|
|
|
@@ -2651,6 +2660,22 @@ function checkPrivateNpm(src, workflows, fail, warn) {
|
|
|
2651
2660
|
for (const f of all) (f.level === "fail" ? fail : warn)(f.text);
|
|
2652
2661
|
}
|
|
2653
2662
|
|
|
2663
|
+
// ---- the release workflow runs on the repo's own runners when private (#453) -------------------
|
|
2664
|
+
// A hosted job on a private repo is billed, and a billing refusal fails the release run at trunk's
|
|
2665
|
+
// head — `colab ship` then reads trunk as red. Visibility from the GitHub API, read only when a
|
|
2666
|
+
// release workflow exists; unreadable → nothing reported (advisory, never invented).
|
|
2667
|
+
function checkReleaseRunner(src, workflows, warn) {
|
|
2668
|
+
const readFile = (p) => src.readFile(p);
|
|
2669
|
+
const hasRelease = (workflows || []).some((wf) => releaseRunner.RELEASE_AUTO_RUN.test(readFile(`.github/workflows/${wf}`) || ""));
|
|
2670
|
+
if (!hasRelease) return;
|
|
2671
|
+
const meta = src.metadata ? src.metadata() : { status: "unreadable" };
|
|
2672
|
+
let visibility = null;
|
|
2673
|
+
if (meta.status === "ok" && meta.data) {
|
|
2674
|
+
visibility = meta.data.visibility || (meta.data.private === true ? "private" : meta.data.private === false ? "public" : null);
|
|
2675
|
+
}
|
|
2676
|
+
for (const text of releaseRunner.findings({ readFile, workflows, visibility })) warn(text);
|
|
2677
|
+
}
|
|
2678
|
+
|
|
2654
2679
|
function checkRunbook(src, runbook, fail, warn, why = "deploy: manual") {
|
|
2655
2680
|
if (runbook === null || runbook === "") {
|
|
2656
2681
|
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 };
|