@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 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,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
- const externalTagDeploy = deploy === "tag" && !deployWorkflows.length;
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 (!deployWorkflows.length) {
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: deployWorkflows.length > 0, deployWorkflowNames: deployWorkflows };
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
- function fastRouteDeployFindings({ readFile, workflows, cfg }) {
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
@@ -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.24"
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 };