@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 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
- return { status: "ok", data: JSON.parse(out) };
584
+ r = { status: "ok", data: JSON.parse(out) };
579
585
  } catch {
580
- return { status: "unreadable" };
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
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.22"
30
+ "version": "1.12.0-rc.23"
31
31
  }
@@ -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
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
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
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
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 (self-hosted label, etc.).
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 };