@futurelastic/colab-handbook 1.12.0-rc.21 → 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
@@ -1647,7 +1655,9 @@ function auditRepo(target, ctx) {
1647
1655
  checkPrereleaseTagTrigger(src, workflows, deploy, fail, warn);
1648
1656
  checkReleaseAuto(src, workflows, cfg, warn);
1649
1657
  checkFastRouteDeploy(src, workflows, cfg, fail);
1658
+ checkDeployContainer(src, workflows, cfg, warn);
1650
1659
  checkPrivateNpm(src, workflows, fail, warn);
1660
+ checkReleaseRunner(src, workflows, warn);
1651
1661
 
1652
1662
  const runbook = cfg && "runbook" in cfg ? cfg.runbook : null;
1653
1663
 
@@ -2603,6 +2613,30 @@ function checkFastRouteDeploy(src, workflows, cfg, fail) {
2603
2613
  for (const text of fastRouteDeployFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) fail(text);
2604
2614
  }
2605
2615
 
2616
+ // ---- a deploy-container copy needs a version to wait for (#452) ---------------------------------
2617
+ // templates/deploy-container.yml is green only on a verified running version, read from
2618
+ // release.health-url (or a HEALTH_URL the repo set in its own copy). A copy with neither fails every
2619
+ // deploy at its first step — advisory, not a failure: the repo owns the file, and may have wired
2620
+ // the URL in by hand.
2621
+ function deployContainerFindings({ readFile, workflows, cfg }) {
2622
+ const effective = cfg ? releasePolicy.evaluateRelease(cfg).effective : null;
2623
+ if (effective && effective.healthUrl) return [];
2624
+ const out = [];
2625
+ for (const wf of workflows || []) {
2626
+ const text = readFile(`.github/workflows/${wf}`);
2627
+ if (!text) continue;
2628
+ const stamp = parseWorkflowStamp(text);
2629
+ const isCopy = (stamp && stamp.name === "deploy-container") || /deploy-container-run\.mjs/.test(text);
2630
+ if (!isCopy) continue;
2631
+ if (/^\s*HEALTH_URL:\s*["']?https:\/\//m.test(text)) continue;
2632
+ out.push(`${wf} deploys through deploy-container-run, but release.health-url is not declared — its verify step has no version to wait for, so every deploy fails; declare release.health-url (route deploy-tag or deploy-tag-fast)`);
2633
+ }
2634
+ return out;
2635
+ }
2636
+ function checkDeployContainer(src, workflows, cfg, warn) {
2637
+ for (const text of deployContainerFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) warn(text);
2638
+ }
2639
+
2606
2640
  // ---- a private repo never publishes to public npm (#432) ---------------------
2607
2641
  // Visibility is read from the GitHub API, and only when the repo has an npm surface at all (so an
2608
2642
  // npm-free repo costs no API call). Unreadable / no remote → reported as a warn, never passed.
@@ -2626,6 +2660,22 @@ function checkPrivateNpm(src, workflows, fail, warn) {
2626
2660
  for (const f of all) (f.level === "fail" ? fail : warn)(f.text);
2627
2661
  }
2628
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
+
2629
2679
  function checkRunbook(src, runbook, fail, warn, why = "deploy: manual") {
2630
2680
  if (runbook === null || runbook === "") {
2631
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.21"
30
+ "version": "1.12.0-rc.23"
31
31
  }
@@ -24,6 +24,9 @@ Starting points you **copy into your own repo**. That is the entire model.
24
24
  | `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. |
25
25
  | `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 for a service's `init`. `*.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). |
26
26
  | `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
27
+ | `deploy-container.yml` | `.github/workflows/deploy-container.yml` | A **container** app on a host whose platform has an API (Portainer today), `deploy: tag` ([CONVENTIONS §6, *A container deploy*](../CONVENTIONS.md#6-releases), #452) | One contract on every host: build each listed image **once** per final tag (`vX.Y.Z` + commit sha), run the pre-deploy hook, have the platform run exactly that tag (all images, one call), green only on a **verified running version** (stack settled, commit and container images checked, then `release.health-url` reporting `X.Y.Z`), roll back to the previous final on a failure after the platform accepted. Triggers: a final tag push (route `deploy-tag`), `workflow_dispatch` with a tag (a manual deploy or rollback), and `workflow_call` — route `deploy-tag-fast` reaches it from `release-auto.yml`'s commented `deploy` job, like `dist-refs.yml` from its release run. Needs its two scripts below. One secret: `PORTAINER_API_KEY`, a non-admin key owning only this app's stack. **Every redeploy recreates the containers.** Does **not** change your exposure. |
28
+ | `deploy-container-run.mjs` | `.github/deploy/deploy-container-run.mjs` | Pairs with `deploy-container.yml` | The driver: builds, runs the hook, calls the adapter, verifies, rolls back, records. Node ≥ 18, zero dependencies; shells out to `git`, `docker`, `gh`. `colab template deploy-container-run.mjs --dest <path>`, `--dest` required, stamped on line 2. |
29
+ | `deploy-adapter-portainer.mjs` | `.github/deploy/deploy-adapter-portainer.mjs` — **beside** the driver, which loads `./deploy-adapter-<DEPLOY_ADAPTER>.mjs` | Pairs with `deploy-container.yml` | The Portainer adapter: git stacks redeploy `refs/tags/vX.Y.Z`, file stacks update with the compose file; the stack's **whole** `Env` is sent back with `IMAGE_TAG` replaced; 409 waited out and retried, any other error a hard failure (nothing changed). Another platform = another file exporting the same five names (`name`, `configFromEnv`, `snapshot`, `deploy`, `restore`). |
27
30
  | `repo-CLAUDE-block.md` | *paste into* `CLAUDE.md` | Every adopting repo | The discovery hook — how an agent finds the handbook at all. |
28
31
  | `gotchas-d-README.md` | `docs/gotchas.d/README.md` | Any repo starting a `docs/gotchas.d/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Naming rule (`<issue>-<slug>.md`) and the don't-copy-back rule against an existing `docs/gotchas.md`. Optional — writing the first gotcha entry does not require copying this in first. |
29
32
  | `adr-README.md` | `docs/adr/README.md` | Any repo starting a `docs/adr/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Same issue-keyed naming rule as `gotchas-d-README.md`, applied to architecture decision records instead of gotchas — an existing sequentially-numbered `docs/adr/` is left as-is; only new decisions use `<issue>-<slug>.md`. Optional, same as above. |
@@ -116,6 +119,9 @@ directory into ~45 repos and was wrong — fixed 2026-08-20.
116
119
  colab template ci-node --dest .github/workflows/ci.yml
117
120
  colab template release-tag --dest .github/workflows/release.yml
118
121
  colab template deploy-xserver --dest .github/workflows/deploy-xserver.yml
122
+ colab template deploy-container --dest .github/workflows/deploy-container.yml
123
+ colab template deploy-container-run.mjs --dest .github/deploy/deploy-container-run.mjs
124
+ colab template deploy-adapter-portainer.mjs --dest .github/deploy/deploy-adapter-portainer.mjs
119
125
  colab template docs-lint.mjs --dest tools/docs-lint.mjs # --dest is required for this one
120
126
  ```
121
127
 
@@ -0,0 +1,206 @@
1
+ #!/usr/bin/env node
2
+ // deploy adapter (Portainer) — TEMPLATE. Copy me into your repo next to deploy-container-run.mjs
3
+ // (`colab template deploy-adapter-portainer.mjs --dest .github/deploy/deploy-adapter-portainer.mjs`)
4
+ // and OWN the copy, exactly like the workflow templates (templates/README.md). Nothing here calls
5
+ // back to the handbook, and nothing here updates itself.
6
+ //
7
+ // WHAT IT IS. One platform adapter behind templates/deploy-container.yml (colab-handbook #452). The
8
+ // driver (deploy-container-run.mjs) builds the images and decides WHAT runs; an adapter only tells
9
+ // ONE platform "run exactly this tag" and proves that it did. A second platform is a second file
10
+ // exporting the same five names (`name`, `configFromEnv`, `snapshot`, `deploy`, `restore`) — the
11
+ // consuming workflow then changes only DEPLOY_ADAPTER, never its steps.
12
+ //
13
+ // TOPOLOGY. Every server runs its own Portainer: no central panel, no Portainer Agents. So the
14
+ // whole per-app configuration is THAT host's Portainer URL + endpointId + stack id + one key:
15
+ //
16
+ // PORTAINER_URL https://portainer.app.example.com — a DNS name, never an address
17
+ // PORTAINER_ENDPOINT_ID the environment (endpoint) id the stack lives in
18
+ // PORTAINER_STACK_ID the stack's id
19
+ // PORTAINER_STACK_KIND git (default) | file
20
+ // PORTAINER_COMPOSE_FILE file stacks only: the compose file sent as the stack content
21
+ // PORTAINER_API_KEY the secret — an access token of a NON-ADMIN user that owns only this
22
+ // app's stack. Never an admin key: a leaked deploy key must reach one app.
23
+ //
24
+ // MEASURED (Portainer CE 2.45.1, git stacks):
25
+ // - `PUT /api/stacks/{id}/git/redeploy` honours `RepositoryReferenceName: refs/tags/vX.Y.Z`.
26
+ // - 200 only means ACCEPTED: the redeploy is asynchronous. `Status` is 3 while deploying and 1
27
+ // once active; `GitConfig.ConfigHash` then holds the commit actually deployed.
28
+ // - 409 = a deploy is already in progress (busy: wait, retry). 500 = a hard failure, returned
29
+ // synchronously, and nothing changed (e.g. a tag that does not exist).
30
+ // - `Env` sent on redeploy REPLACES the stack's whole list — so this sends the full current list
31
+ // with IMAGE_TAG replaced, never only the changed key.
32
+ // - EVERY REDEPLOY RECREATES THE CONTAINERS, even when the compose file did not change: expect a
33
+ // short restart on every deploy, including a rollback.
34
+ // - A call can return 200 while the environment refused the container (e.g. a bind mount blocked
35
+ // for a non-admin user). So success is read from what RUNS — the running containers' image —
36
+ // never from the HTTP status.
37
+ // NOT MEASURED (assumptions, each a place to check first if your deploy misbehaves): file-stack
38
+ // `PUT /api/stacks/{id}` being asynchronous too (this polls either way); a non-admin, stack-owning
39
+ // key being allowed to list its stack's containers through the Docker proxy; private-repository
40
+ // auth on redeploy (this reuses a stored git credential id, and refuses otherwise).
41
+
42
+ export const name = 'portainer';
43
+
44
+ export class AdapterError extends Error {
45
+ /** kind: 'hard' (refused synchronously, nothing changed) | 'busy' (a deploy never freed up) |
46
+ * 'refused' (accepted, but what runs is not what was asked) | 'config'. */
47
+ constructor(kind, message, { changed = false } = {}) {
48
+ super(message);
49
+ this.kind = kind;
50
+ this.changed = changed;
51
+ }
52
+ }
53
+
54
+ const STATUS_ACTIVE = 1;
55
+ const STATUS_DEPLOYING = 3;
56
+
57
+ /** The adapter's configuration from env; throws naming every missing key. */
58
+ export function configFromEnv(env) {
59
+ const need = ['PORTAINER_URL', 'PORTAINER_ENDPOINT_ID', 'PORTAINER_STACK_ID', 'PORTAINER_API_KEY'];
60
+ const missing = need.filter((k) => !String(env[k] || '').trim());
61
+ if (missing.length) throw new AdapterError('config', `portainer adapter: missing ${missing.join(', ')}`);
62
+ const kind = String(env.PORTAINER_STACK_KIND || 'git').trim();
63
+ if (!['git', 'file'].includes(kind)) throw new AdapterError('config', `PORTAINER_STACK_KIND is "${kind}", expected git or file`);
64
+ return {
65
+ url: String(env.PORTAINER_URL).trim().replace(/\/+$/, ''),
66
+ endpointId: String(env.PORTAINER_ENDPOINT_ID).trim(),
67
+ stackId: String(env.PORTAINER_STACK_ID).trim(),
68
+ kind,
69
+ composeFile: String(env.PORTAINER_COMPOSE_FILE || 'docker-compose.yml').trim(),
70
+ apiKey: String(env.PORTAINER_API_KEY).trim(),
71
+ };
72
+ }
73
+
74
+ /** The full env list with every `kv` key replaced in place or appended — never a partial list. */
75
+ export function mergeEnv(list, kv) {
76
+ const out = (list || []).map((e) => ({ name: e.name, value: e.value }));
77
+ for (const [k, v] of Object.entries(kv)) {
78
+ const at = out.findIndex((e) => e.name === k);
79
+ if (at >= 0) out[at] = { name: k, value: v };
80
+ else out.push({ name: k, value: v });
81
+ }
82
+ return out;
83
+ }
84
+
85
+ async function call(cfg, io, method, path, body) {
86
+ const res = await io.fetch(`${cfg.url}${path}`, {
87
+ method,
88
+ headers: { 'X-API-Key': cfg.apiKey, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
89
+ body: body === undefined ? undefined : JSON.stringify(body),
90
+ });
91
+ const text = await res.text();
92
+ let json = null;
93
+ try { json = text ? JSON.parse(text) : null; } catch { json = null; }
94
+ return { status: res.status, json, text };
95
+ }
96
+
97
+ async function getStack(cfg, io) {
98
+ const r = await call(cfg, io, 'GET', `/api/stacks/${cfg.stackId}`);
99
+ if (r.status !== 200 || !r.json) throw new AdapterError('hard', `GET /api/stacks/${cfg.stackId} answered ${r.status}: ${r.text.slice(0, 200)}`);
100
+ return r.json;
101
+ }
102
+
103
+ /** What the stack runs now — the rollback target and the base of every Env sent. */
104
+ export async function snapshot(cfg, io) {
105
+ const s = await getStack(cfg, io);
106
+ const snap = {
107
+ kind: cfg.kind,
108
+ name: s.Name,
109
+ ref: (s.GitConfig && s.GitConfig.ReferenceName) || null,
110
+ configHash: (s.GitConfig && s.GitConfig.ConfigHash) || null,
111
+ gitCredentialId: (s.GitConfig && s.GitConfig.Authentication && s.GitConfig.Authentication.GitCredentialID) || 0,
112
+ privateRepo: Boolean(s.GitConfig && s.GitConfig.Authentication),
113
+ env: (s.Env || []).map((e) => ({ name: e.name, value: e.value })),
114
+ fileContent: null,
115
+ };
116
+ if (cfg.kind === 'file') {
117
+ const f = await call(cfg, io, 'GET', `/api/stacks/${cfg.stackId}/file`);
118
+ if (f.status !== 200 || !f.json) throw new AdapterError('hard', `GET /api/stacks/${cfg.stackId}/file answered ${f.status}`);
119
+ snap.fileContent = f.json.StackFileContent;
120
+ }
121
+ return snap;
122
+ }
123
+
124
+ function requestFor(cfg, snap, { ref, env, fileContent }) {
125
+ const q = `?endpointId=${encodeURIComponent(cfg.endpointId)}`;
126
+ if (cfg.kind === 'git') {
127
+ const body = { RepositoryReferenceName: ref, Env: env, PullImage: true, Prune: true, RepositoryAuthentication: false };
128
+ if (snap.privateRepo) {
129
+ if (!snap.gitCredentialId) {
130
+ throw new AdapterError('hard', 'the stack pulls a private repository without a stored git credential — unsupported here (unmeasured); store a git credential in Portainer for the stack');
131
+ }
132
+ body.RepositoryAuthentication = true;
133
+ body.RepositoryGitCredentialID = snap.gitCredentialId;
134
+ }
135
+ return { method: 'PUT', path: `/api/stacks/${cfg.stackId}/git/redeploy${q}`, body };
136
+ }
137
+ return { method: 'PUT', path: `/api/stacks/${cfg.stackId}${q}`, body: { StackFileContent: fileContent, Env: env, PullImage: true, Prune: true } };
138
+ }
139
+
140
+ /** Send one deploy request: 409 waited out and retried, any other non-200 a hard failure. */
141
+ async function send(cfg, snap, req, io) {
142
+ const t = io.timing;
143
+ const busyUntil = io.now() + t.busyTimeoutS * 1000;
144
+ for (;;) {
145
+ const r = await call(cfg, io, req.method, req.path, req.body);
146
+ if (r.status === 200) return;
147
+ if (r.status === 409) {
148
+ if (io.now() >= busyUntil) throw new AdapterError('busy', `the stack stayed busy (409) for ${t.busyTimeoutS}s — nothing was changed by this run`);
149
+ io.log(`portainer: a deploy is already in progress (409) — waiting for it, then retrying`);
150
+ await waitWhileDeploying(cfg, io, busyUntil);
151
+ continue;
152
+ }
153
+ throw new AdapterError('hard', `${req.method} ${req.path.split('?')[0]} answered ${r.status}: ${r.text.slice(0, 300)} — nothing changed`);
154
+ }
155
+ }
156
+
157
+ async function waitWhileDeploying(cfg, io, until) {
158
+ for (;;) {
159
+ const s = await getStack(cfg, io);
160
+ if (s.Status !== STATUS_DEPLOYING) return s;
161
+ if (io.now() >= until) return s;
162
+ await io.sleep(io.timing.pollMs);
163
+ }
164
+ }
165
+
166
+ /**
167
+ * Accepted is not deployed: wait for the stack to leave "deploying", require it active, require the
168
+ * git commit asked for, then require every listed image running at `tag`.
169
+ */
170
+ async function settle(cfg, { tag, tagSha, images }, io) {
171
+ const until = io.now() + io.timing.deployTimeoutS * 1000;
172
+ const s = await waitWhileDeploying(cfg, io, until);
173
+ if (s.Status === STATUS_DEPLOYING) throw new AdapterError('refused', `the stack was still deploying after ${io.timing.deployTimeoutS}s`, { changed: true });
174
+ if (s.Status !== STATUS_ACTIVE) throw new AdapterError('refused', `the stack settled with Status ${s.Status}, not active (1)`, { changed: true });
175
+ if (cfg.kind === 'git' && tagSha) {
176
+ const got = s.GitConfig && s.GitConfig.ConfigHash;
177
+ if (got !== tagSha) throw new AdapterError('refused', `the stack runs commit ${got || '(none)'}, not ${tag}'s ${tagSha}`, { changed: true });
178
+ }
179
+ if (!images || !images.length) return;
180
+ const filters = encodeURIComponent(JSON.stringify({ label: [`com.docker.compose.project=${s.Name}`] }));
181
+ const r = await call(cfg, io, 'GET', `/api/endpoints/${encodeURIComponent(cfg.endpointId)}/docker/containers/json?all=1&filters=${filters}`);
182
+ if (r.status !== 200 || !Array.isArray(r.json)) {
183
+ throw new AdapterError('refused', `could not list the stack's containers (${r.status}) — success is read from what runs, so this fails`, { changed: true });
184
+ }
185
+ const notRunning = images.filter((ref) => !r.json.some((c) => c.Image === `${ref}:${tag}` && c.State === 'running'));
186
+ if (notRunning.length) {
187
+ const seen = r.json.map((c) => `${c.Image} (${c.State})`).join(', ') || 'no containers';
188
+ throw new AdapterError('refused', `accepted, but not running ${notRunning.map((i) => `${i}:${tag}`).join(', ')} — found ${seen}`, { changed: true });
189
+ }
190
+ }
191
+
192
+ /** Run exactly `target.tag`: every listed image in one call, then prove it runs. */
193
+ export async function deploy(cfg, target, io, snap) {
194
+ const base = snap || (await snapshot(cfg, io));
195
+ const env = mergeEnv(base.env, { IMAGE_TAG: target.tag, ...(target.env || {}) });
196
+ const req = requestFor(cfg, base, { ref: `refs/tags/${target.tag}`, env, fileContent: target.fileContent });
197
+ await send(cfg, base, req, io);
198
+ await settle(cfg, target, io);
199
+ }
200
+
201
+ /** Put back exactly what `snap` recorded — its ref, its whole Env, its file content. */
202
+ export async function restore(cfg, snap, io, { tag, images } = {}) {
203
+ const req = requestFor(cfg, snap, { ref: snap.ref, env: snap.env, fileContent: snap.fileContent });
204
+ await send(cfg, snap, req, io);
205
+ await settle(cfg, { tag, tagSha: snap.configHash, images: tag ? images : [] }, io);
206
+ }
@@ -0,0 +1,268 @@
1
+ #!/usr/bin/env node
2
+ // deploy-container-run — TEMPLATE. Copy me into your repo
3
+ // (`colab template deploy-container-run.mjs --dest .github/deploy/deploy-container-run.mjs`), next
4
+ // to your platform adapter (`deploy-adapter-<platform>.mjs`, same directory), and OWN the copy.
5
+ // templates/deploy-container.yml runs it. Nothing here calls back to the handbook.
6
+ //
7
+ // THE CONTRACT (colab-handbook #452) — one deploy path for every container app, on every host:
8
+ // 1. build every listed image ONCE per final tag (tagged vX.Y.Z and the commit sha) and push it;
9
+ // 2. run the repo's pre-deploy hook — a failure stops the run before the platform is touched;
10
+ // 3. tell the platform, through the adapter, to run exactly vX.Y.Z — all images in one call;
11
+ // 4. green only when what RUNS is vX.Y.Z: the adapter checks the stack and its containers, then
12
+ // release.health-url must report X.Y.Z;
13
+ // 5. any failure after the platform accepted the call rolls back to what ran before (the
14
+ // previous final), verifies that, and still fails the run. A manual rollback is a re-run
15
+ // with the previous tag.
16
+ // The outcome — "running vX.Y.Z at <time>" or the failure — goes to the run summary and, when one
17
+ // exists, to the release issue (the issue carrying `<!-- colab:release version=vX.Y.Z -->`).
18
+ //
19
+ // CONFIGURATION (env; the workflow's one env block):
20
+ // DEPLOY_ADAPTER portainer (default) — loads ./deploy-adapter-<name>.mjs beside this file
21
+ // DEPLOY_IMAGES one image per line: `<image-ref> <build-context> [<dockerfile>]`
22
+ // PRE_DEPLOY optional shell command; gets TAG and PREVIOUS_TAG in its env
23
+ // HEALTH_URL the version URL; else --health-url; else release.health-url in
24
+ // .github/project.yml
25
+ // VERIFY_TIMEOUT_SECONDS 600 · POLL_INTERVAL_MS 5000 · DEPLOY_TIMEOUT_SECONDS 600 ·
26
+ // BUSY_TIMEOUT_SECONDS 600
27
+ // GH_TOKEN, GITHUB_REPOSITORY — to record on the release issue (optional)
28
+ //
29
+ // Usage: node deploy-container-run.mjs --tag vX.Y.Z [--health-url URL] [--tag-sha SHA]
30
+ // Exit: 0 = running vX.Y.Z, verified · 1 = not deployed (rolled back where something changed).
31
+
32
+ import { spawnSync } from 'node:child_process';
33
+ import fs from 'node:fs';
34
+ import { fileURLToPath } from 'node:url';
35
+
36
+ const FINAL_TAG = /^v(\d+)\.(\d+)\.(\d+)$/;
37
+
38
+ /** `<ref> <context> [<dockerfile>]` per line; blank lines and `#` comments skipped. */
39
+ export function parseImages(text) {
40
+ const out = [];
41
+ for (const raw of String(text || '').split('\n')) {
42
+ const line = raw.replace(/#.*$/, '').trim();
43
+ if (!line) continue;
44
+ const [ref, context, dockerfile] = line.split(/\s+/);
45
+ if (!ref || !context) throw new Error(`DEPLOY_IMAGES line "${line}" needs <image-ref> <build-context> [<dockerfile>]`);
46
+ if (/:[^/]*$/.test(ref.split('/').pop())) throw new Error(`DEPLOY_IMAGES ref "${ref}" carries a tag — list it without one; the tag is the release's`);
47
+ out.push({ ref, context, dockerfile: dockerfile || `${context.replace(/\/+$/, '')}/Dockerfile` });
48
+ }
49
+ return out;
50
+ }
51
+
52
+ /** Does `body` report `version` — as a whole version, so 1.2.1 never matches 1.2.10 or 11.2.1? */
53
+ export function reportsVersion(body, version) {
54
+ const v = String(version).replace(/^v/, '').replace(/\./g, '\\.');
55
+ return new RegExp(`(?<![0-9.])v?${v}(?![0-9]|\\.[0-9])`).test(String(body || ''));
56
+ }
57
+
58
+ /** release.health-url from a project.yml text — block style only; anything else reads as absent. */
59
+ export function readHealthUrl(text) {
60
+ const lines = String(text || '').split('\n');
61
+ const at = lines.findIndex((l) => /^release:\s*(#.*)?$/.test(l));
62
+ if (at < 0) return null;
63
+ for (let i = at + 1; i < lines.length; i++) {
64
+ const l = lines[i];
65
+ if (l.trim() && !/^\s/.test(l)) break;
66
+ const m = /^\s+health-url:\s*["']?([^"'\s#]+)["']?\s*(#.*)?$/.exec(l);
67
+ if (m) return m[1];
68
+ }
69
+ return null;
70
+ }
71
+
72
+ /** The newest strict final tag (vN.N.N, no pre-release) below `current`, or null. */
73
+ export function previousFinalTag(tags, current) {
74
+ const key = (t) => { const m = FINAL_TAG.exec(t); return m ? [+m[1], +m[2], +m[3]] : null; };
75
+ const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
76
+ const cur = key(current);
77
+ const older = (tags || []).map((t) => [t, key(t)]).filter(([, k]) => k && (!cur || cmp(k, cur) < 0));
78
+ older.sort((a, b) => cmp(b[1], a[1]));
79
+ return older.length ? older[0][0] : null;
80
+ }
81
+
82
+ export async function loadAdapter(name) {
83
+ if (!/^[a-z0-9-]+$/.test(name)) throw new Error(`DEPLOY_ADAPTER "${name}" is not an adapter name`);
84
+ return import(new URL(`./deploy-adapter-${name}.mjs`, import.meta.url));
85
+ }
86
+
87
+ function sh(cmd, args, opts = {}) {
88
+ const r = spawnSync(cmd, args, { encoding: 'utf8', stdio: opts.inherit ? 'inherit' : 'pipe', env: opts.env || process.env });
89
+ return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
90
+ }
91
+
92
+ function defaultIo(env) {
93
+ return {
94
+ env,
95
+ fetch: globalThis.fetch,
96
+ sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
97
+ now: () => Date.now(),
98
+ log: (m) => console.log(m),
99
+ error: (m) => console.log(`::error::${m}`),
100
+ sh,
101
+ summary: (line) => { if (env.GITHUB_STEP_SUMMARY) fs.appendFileSync(env.GITHUB_STEP_SUMMARY, `${line}\n`); },
102
+ readFile: (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } },
103
+ };
104
+ }
105
+
106
+ async function waitForVersion(url, version, io, timeoutS) {
107
+ const until = io.now() + timeoutS * 1000;
108
+ let last = '';
109
+ for (;;) {
110
+ try {
111
+ const res = await io.fetch(url, { headers: { 'Cache-Control': 'no-cache' } });
112
+ last = await res.text();
113
+ if (res.ok && reportsVersion(last, version)) return true;
114
+ } catch (e) { last = String(e && e.message); }
115
+ if (io.now() >= until) return false;
116
+ await io.sleep(io.timing.pollMs);
117
+ }
118
+ }
119
+
120
+ function record(io, tag, line) {
121
+ io.summary(line);
122
+ const repo = io.env.GITHUB_REPOSITORY;
123
+ if (!repo) return;
124
+ const found = io.sh('gh', ['issue', 'list', '--repo', repo, '--state', 'all', '--search', `"colab:release version=${tag}" in:body`, '--json', 'number', '--jq', '.[0].number // ""']);
125
+ const n = found.status === 0 ? found.stdout.trim() : '';
126
+ if (!n) { io.log(`no release issue for ${tag} — recorded in the run summary only`); return; }
127
+ const c = io.sh('gh', ['issue', 'comment', n, '--repo', repo, '--body', line]);
128
+ if (c.status !== 0) io.log(`could not comment on release issue #${n}: ${c.stderr.trim()}`);
129
+ }
130
+
131
+ function buildOnce(images, tag, sha, io) {
132
+ for (const img of images) {
133
+ if (io.sh('docker', ['manifest', 'inspect', `${img.ref}:${tag}`]).status === 0) {
134
+ io.log(`${img.ref}:${tag} is already pushed — built once per tag, not rebuilt`);
135
+ continue;
136
+ }
137
+ const steps = [
138
+ ['build', '-f', img.dockerfile, '-t', `${img.ref}:${tag}`, '-t', `${img.ref}:${sha}`, img.context],
139
+ ['push', `${img.ref}:${tag}`],
140
+ ['push', `${img.ref}:${sha}`],
141
+ ];
142
+ for (const args of steps) {
143
+ const r = io.sh('docker', args, { inherit: true });
144
+ if (r.status !== 0) throw new Error(`docker ${args[0]} ${img.ref} failed (exit ${r.status})`);
145
+ }
146
+ }
147
+ }
148
+
149
+ /** The whole contract. Returns the exit code. */
150
+ export async function run(opts, io) {
151
+ const env = io.env;
152
+ const tag = opts.tag;
153
+ const fail = (m) => { io.error(m); return 1; };
154
+ if (!FINAL_TAG.test(tag || '')) return fail(`"${tag}" is not a final tag vX.Y.Z — this deploys finals only`);
155
+ const version = tag.slice(1);
156
+ const healthUrl = opts.healthUrl || env.HEALTH_URL || readHealthUrl(io.readFile('.github/project.yml'));
157
+ if (!healthUrl) return fail('no version URL — set release.health-url in .github/project.yml (or HEALTH_URL); a deploy is green only on a verified running version');
158
+
159
+ let images; let adapter; let cfg;
160
+ try {
161
+ images = parseImages(env.DEPLOY_IMAGES);
162
+ if (!images.length) throw new Error('DEPLOY_IMAGES lists no image — list every image this stack runs');
163
+ adapter = await loadAdapter(env.DEPLOY_ADAPTER || 'portainer');
164
+ cfg = adapter.configFromEnv(env);
165
+ } catch (e) { return fail(e.message); }
166
+
167
+ const tagSha = opts.tagSha || io.sh('git', ['rev-parse', `${tag}^{commit}`]).stdout.trim();
168
+ if (!/^[0-9a-f]{40}$/.test(tagSha)) return fail(`could not resolve ${tag} to a commit`);
169
+ const tags = io.sh('git', ['tag', '--list', 'v*']).stdout.split('\n').map((t) => t.trim()).filter(Boolean);
170
+ const previous = previousFinalTag(tags, tag);
171
+ const at = () => new Date(io.now()).toISOString();
172
+
173
+ // 1. Build once.
174
+ try { buildOnce(images, tag, tagSha, io); } catch (e) { record(io, tag, `deploy of ${tag} failed at ${at()}: ${e.message} — nothing deployed`); return fail(e.message); }
175
+
176
+ // 2. Pre-deploy hook — before anything on the platform changes.
177
+ if (env.PRE_DEPLOY && env.PRE_DEPLOY.trim()) {
178
+ const r = io.sh('sh', ['-c', env.PRE_DEPLOY], { inherit: true, env: { ...env, TAG: tag, PREVIOUS_TAG: previous || '' } });
179
+ if (r.status !== 0) {
180
+ record(io, tag, `deploy of ${tag} stopped at ${at()}: the pre-deploy hook failed (exit ${r.status}) — nothing deployed`);
181
+ return fail(`pre-deploy hook failed (exit ${r.status}) — the platform was not called`);
182
+ }
183
+ }
184
+
185
+ // 3. Snapshot, then run exactly this tag.
186
+ const refs = images.map((i) => i.ref);
187
+ let snap;
188
+ try { snap = await adapter.snapshot(cfg, io); } catch (e) {
189
+ record(io, tag, `deploy of ${tag} failed at ${at()}: ${e.message} — nothing deployed`);
190
+ return fail(e.message);
191
+ }
192
+ const fileContent = cfg.kind === 'file' ? io.readFile(cfg.composeFile) : undefined;
193
+ if (cfg.kind === 'file' && fileContent === null) return fail(`compose file ${cfg.composeFile} not found in the checkout`);
194
+
195
+ let reason = null;
196
+ try {
197
+ await adapter.deploy(cfg, { tag, tagSha, images: refs, fileContent }, io, snap);
198
+ if (!(await waitForVersion(healthUrl, version, io, io.timing.verifyTimeoutS))) {
199
+ throw Object.assign(new Error(`${healthUrl} did not report ${version} within ${io.timing.verifyTimeoutS}s`), { changed: true });
200
+ }
201
+ } catch (e) {
202
+ reason = e;
203
+ }
204
+ if (!reason) {
205
+ const line = `running ${tag} at ${at()} — ${healthUrl} reports ${version}`;
206
+ io.log(line);
207
+ record(io, tag, line);
208
+ return 0;
209
+ }
210
+ if (!reason.changed) {
211
+ record(io, tag, `deploy of ${tag} failed at ${at()}: ${reason.message}`);
212
+ return fail(reason.message);
213
+ }
214
+
215
+ // 4. Roll back: what ran before, when it was a final; else the previous final tag.
216
+ const snapTag = snap.ref && /^refs\/tags\//.test(snap.ref) ? snap.ref.slice('refs/tags/'.length) : null;
217
+ const envTag = ((snap.env || []).find((e) => e.name === 'IMAGE_TAG') || {}).value || null;
218
+ const backTag = [snapTag, envTag].find((t) => t && FINAL_TAG.test(t)) || null;
219
+ let back = null; let verified = false;
220
+ try {
221
+ if (backTag) {
222
+ back = backTag;
223
+ await adapter.restore(cfg, snap, io, { tag: backTag, images: refs });
224
+ } else if (previous) {
225
+ back = previous;
226
+ const prevSha = io.sh('git', ['rev-parse', `${previous}^{commit}`]).stdout.trim();
227
+ await adapter.deploy(cfg, { tag: previous, tagSha: prevSha, images: refs, fileContent: snap.fileContent }, io, snap);
228
+ }
229
+ if (back) verified = await waitForVersion(healthUrl, back.slice(1), io, io.timing.verifyTimeoutS);
230
+ } catch (e) {
231
+ io.log(`rollback to ${back} failed: ${e.message}`);
232
+ }
233
+ const line = back
234
+ ? `deploy of ${tag} failed at ${at()}: ${reason.message}; rolled back to ${back} (${verified ? 'verified' : 'NOT verified'})`
235
+ : `deploy of ${tag} failed at ${at()}: ${reason.message}; no rollback target (no previous final tag) — the stack is left as the failed deploy left it`;
236
+ record(io, tag, line);
237
+ return fail(line);
238
+ }
239
+
240
+ function parseArgs(argv) {
241
+ const o = {};
242
+ for (let i = 0; i < argv.length; i++) {
243
+ const a = argv[i];
244
+ const m = /^--([a-z-]+)(?:=(.*))?$/.exec(a);
245
+ if (!m) continue;
246
+ const v = m[2] !== undefined ? m[2] : argv[++i];
247
+ if (m[1] === 'tag') o.tag = v;
248
+ else if (m[1] === 'health-url') o.healthUrl = v;
249
+ else if (m[1] === 'tag-sha') o.tagSha = v;
250
+ }
251
+ return o;
252
+ }
253
+
254
+ if (process.argv[1] && fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1])) {
255
+ const env = process.env;
256
+ const io = defaultIo(env);
257
+ const num = (k, d) => (Number(env[k]) > 0 ? Number(env[k]) : d);
258
+ io.timing = {
259
+ pollMs: num('POLL_INTERVAL_MS', 5000),
260
+ deployTimeoutS: num('DEPLOY_TIMEOUT_SECONDS', 600),
261
+ busyTimeoutS: num('BUSY_TIMEOUT_SECONDS', 600),
262
+ verifyTimeoutS: num('VERIFY_TIMEOUT_SECONDS', 600),
263
+ };
264
+ run(parseArgs(process.argv.slice(2)), io).then((code) => process.exit(code), (e) => {
265
+ console.log(`::error::${e && e.stack ? e.stack : e}`);
266
+ process.exit(1);
267
+ });
268
+ }
@@ -0,0 +1,161 @@
1
+ # Deploy (container, platform adapter) — TEMPLATE. Copy me into your repo at .github/workflows/deploy-container.yml.
2
+ #
3
+ # This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
4
+ # Edit it freely; nothing calls this file remotely and nothing will update it for you.
5
+ #
6
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
7
+ #
8
+ # It needs its two scripts beside each other in your repo (copy-and-own as well):
9
+ # colab template deploy-container-run.mjs --dest .github/deploy/deploy-container-run.mjs
10
+ # colab template deploy-adapter-portainer.mjs --dest .github/deploy/deploy-adapter-portainer.mjs
11
+ #
12
+ # For: a container app whose host runs a platform with an API (Portainer today). ONE CONTRACT,
13
+ # every host (colab-handbook #452):
14
+ # 1. build every image ONCE per final tag — tagged vX.Y.Z and the commit sha — and push it;
15
+ # 2. run your pre-deploy hook (a database snapshot, say) — a failure stops before anything changes;
16
+ # 3. tell the platform "run exactly vX.Y.Z", all images in one call;
17
+ # 4. green only on a verified running version: the platform's own state (the stack settled, the
18
+ # commit it deployed, the image its containers run), then release.health-url reporting X.Y.Z;
19
+ # 5. a failure after the platform accepted the call rolls back to what ran before and still fails
20
+ # the run. ROLLBACK BY HAND = run this workflow (Actions → Run workflow) with the previous tag.
21
+ # The outcome — "running vX.Y.Z at <time>", or the failure — is written to the run summary and to
22
+ # the release issue when there is one.
23
+ #
24
+ # NOT for: shared hosting without a container runtime (templates/deploy-xserver.yml), or a host
25
+ # that pulls its own updates (a platform polling a branch) — that is a different shape.
26
+ #
27
+ # ─────────────────────────────────────────────────────────────────────────────
28
+ # THIS FILE DOES NOT CHANGE YOUR REPO'S EXPOSURE (OR LEGACY TIER).
29
+ #
30
+ # It is the `deploy: tag` shape with an in-repo deploy workflow (`channels: [workflow]`). A tag
31
+ # push deploys only where project.yml already says `deploy: tag`; adopting this file is not the
32
+ # checklist that changes that (CONVENTIONS.md §9).
33
+ #
34
+ # TWO ENTRY POINTS, ONE DEPLOY PATH:
35
+ # - route deploy-tag: a human pushes (or the Releases page creates) the final vX.Y.Z → the
36
+ # `push: tags` trigger below.
37
+ # - route deploy-tag-fast: release-auto.yml tags the final itself, and a tag pushed with
38
+ # GITHUB_TOKEN starts no `push: tags` run — so its `deploy` job calls THIS file through
39
+ # `workflow_call` (templates/release-auto.yml shows the job to paste). Same steps, same checks.
40
+ #
41
+ # SECRETS ARE NAMED HERE, NEVER VALUED.
42
+ # - `secrets.PORTAINER_API_KEY` — ONE KEY PER APP, the access token of a NON-ADMIN platform user
43
+ # that owns only this app's stack. Never an admin key: a leaked deploy key must reach one app.
44
+ # - `secrets.REGISTRY_PASSWORD` — optional; the registry login falls back to the job's
45
+ # `github.token`, which is enough for GHCR with `packages: write`.
46
+ # Everything else is configuration in the env block of the last step.
47
+ #
48
+ # TOPOLOGY. Every server runs its own Portainer — there is no central panel and no Portainer
49
+ # Agent. So the per-app configuration is THAT host's Portainer URL + endpointId + stack id + key.
50
+ # Hosts are named by DNS name, never by address. The runner reaches the platform directly on the
51
+ # LAN or over a VPN — this file does not care which, as long as `runs-on` is a runner that can.
52
+ #
53
+ # EVERY REDEPLOY RECREATES THE CONTAINERS, even when the compose file did not change (measured on
54
+ # Portainer CE 2.45.1) — expect a short restart on every deploy, a rollback included.
55
+ #
56
+ # YOUR COMPOSE FILE names each image as `<image-ref>:${IMAGE_TAG}`. The adapter sets IMAGE_TAG in
57
+ # the stack's environment and sends the WHOLE current environment back — the platform replaces the
58
+ # list wholesale, so a partial list would delete your other variables.
59
+
60
+ name: Deploy (container)
61
+
62
+ on:
63
+ push:
64
+ tags: ["v*.*.*", "!v*.*.*-*"] # finals only — a candidate vX.Y.Z-rc.N never deploys
65
+ workflow_dispatch:
66
+ inputs:
67
+ tag:
68
+ description: "Final tag to deploy (vX.Y.Z) — the previous one rolls back by hand"
69
+ required: true
70
+ type: string
71
+ workflow_call:
72
+ inputs:
73
+ tag:
74
+ description: "Final tag to deploy (vX.Y.Z)"
75
+ required: true
76
+ type: string
77
+ health-url:
78
+ description: "Version URL (release.health-url); read from .github/project.yml when empty"
79
+ required: false
80
+ type: string
81
+ default: ""
82
+ secrets:
83
+ PORTAINER_API_KEY:
84
+ required: false
85
+ REGISTRY_PASSWORD:
86
+ required: false
87
+
88
+ # One deploy at a time per repo, never cancelled half-way: a cancelled deploy is a stack in an
89
+ # unknown state. A fixed group, because under workflow_call `github.workflow` is the CALLER's name.
90
+ concurrency:
91
+ group: deploy-container-${{ github.repository }}
92
+ cancel-in-progress: false
93
+
94
+ permissions:
95
+ contents: read
96
+
97
+ jobs:
98
+ deploy:
99
+ name: Deploy the final
100
+ runs-on: ubuntu-latest # EDIT: a runner that reaches your platform (LAN or VPN) and has docker.
101
+ environment: production # EDIT: the GitHub environment holding PORTAINER_API_KEY, or remove.
102
+ permissions:
103
+ contents: read # check out the tag
104
+ packages: write # push the images (GHCR); drop it for another registry
105
+ issues: write # record the outcome on the release issue
106
+ timeout-minutes: 45
107
+ steps:
108
+ - name: Resolve the tag to deploy
109
+ id: tag
110
+ env:
111
+ INPUT_TAG: ${{ inputs.tag }}
112
+ run: |
113
+ set -euo pipefail
114
+ TAG="${INPUT_TAG:-$GITHUB_REF_NAME}"
115
+ if ! printf '%s' "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
116
+ echo "::error::\"$TAG\" is not a final tag vX.Y.Z — a candidate (-rc.N) or a branch never deploys"
117
+ exit 1
118
+ fi
119
+ echo "tag=$TAG" >> "$GITHUB_OUTPUT"
120
+
121
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
122
+ with:
123
+ ref: refs/tags/${{ steps.tag.outputs.tag }}
124
+ fetch-depth: 0 # every tag: the rollback target is the previous final
125
+ persist-credentials: false # nothing here pushes to git
126
+
127
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
128
+ with:
129
+ node-version: "22"
130
+
131
+ - name: Log in to the image registry
132
+ env:
133
+ REGISTRY: ghcr.io # EDIT: your registry host
134
+ REGISTRY_USER: ${{ github.actor }} # EDIT: the registry user, when not GHCR
135
+ REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD || github.token }}
136
+ run: |
137
+ set -euo pipefail
138
+ printf '%s' "$REGISTRY_PASSWORD" | docker login "$REGISTRY" -u "$REGISTRY_USER" --password-stdin
139
+
140
+ - name: Build once, run exactly this tag, verify (deploy-container-run)
141
+ env:
142
+ DEPLOY_ADAPTER: portainer
143
+ # EDIT: every image this stack runs, one per line: <image-ref> <build-context> [<dockerfile>].
144
+ DEPLOY_IMAGES: |
145
+ ghcr.io/${{ github.repository }} .
146
+ # EDIT: optional — runs before the platform is called, with TAG and PREVIOUS_TAG set; a
147
+ # non-zero exit stops the deploy before anything changes (a database snapshot, say).
148
+ PRE_DEPLOY: ""
149
+ PORTAINER_URL: https://portainer.app.example.com # EDIT: this host's own Portainer
150
+ PORTAINER_ENDPOINT_ID: "1" # EDIT
151
+ PORTAINER_STACK_ID: "1" # EDIT
152
+ PORTAINER_STACK_KIND: git # EDIT: git (the stack pulls this repo at the tag) | file
153
+ PORTAINER_COMPOSE_FILE: docker-compose.yml # file stacks only: sent as the stack content
154
+ PORTAINER_API_KEY: ${{ secrets.PORTAINER_API_KEY }}
155
+ HEALTH_URL: ${{ inputs.health-url }} # empty → release.health-url in .github/project.yml
156
+ VERIFY_TIMEOUT_SECONDS: "600" # EDIT: how long the new version may take to report itself
157
+ DEPLOY_TIMEOUT_SECONDS: "600"
158
+ BUSY_TIMEOUT_SECONDS: "600"
159
+ GH_TOKEN: ${{ github.token }}
160
+ TAG: ${{ steps.tag.outputs.tag }}
161
+ run: node .github/deploy/deploy-container-run.mjs --tag "$TAG"
@@ -84,7 +84,10 @@
84
84
  # `colab release cut --auto` tags the FINAL vX.Y.Z on every green main head — no candidate, no
85
85
  # test period — and the `deploy` job below deploys that tag in this same run, then polls
86
86
  # release.health-url until it reports the version. Its deploy step is an EDIT point: replace it
87
- # with your deploy (it fails loudly until you do). On every other route the job is skipped and the
87
+ # with your deploy (it fails loudly until you do) — or, for a container app, replace the whole job
88
+ # with the commented one under it, which calls templates/deploy-container.yml (#452): the same
89
+ # deploy a human-pushed final runs on route deploy-tag, so both routes share one deploy path, with
90
+ # its own health check and rollback. On every other route the job is skipped and the
88
91
  # run still concludes on the `release` job. EDIT: on this route, a cron more frequent than daily
89
92
  # tags a head that release.final-spacing held back sooner.
90
93
  #
@@ -110,6 +113,26 @@
110
113
  # `npm` job, which sets up its own Node for npm's trusted publishing (EDIT point there for
111
114
  # a package that needs a build). The npm job needs a HANDBOOK_REF that carries #433; an
112
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.
113
136
 
114
137
  name: Release (auto)
115
138
 
@@ -153,7 +176,9 @@ jobs:
153
176
  # the whole run as `skipped` at that main sha, and `colab ship` reads any finished run that is
154
177
  # neither success nor cancelled as "not green". Re-run CI green on that sha and the skipped
155
178
  # Release (auto) row would still sit beside it, refusing every ship until main moves.
156
- 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
157
182
  permissions:
158
183
  contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
159
184
  issues: write # finalize opens / comments on / closes the "release: vX.Y.Z" tracking issue
@@ -481,7 +506,8 @@ jobs:
481
506
  name: Record the npm outcome on the Release
482
507
  needs: [release, npm]
483
508
  if: always() && needs.release.outputs.npm == 'true'
484
- 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
485
511
  permissions:
486
512
  contents: write # edit the Release notes
487
513
  env:
@@ -530,7 +556,7 @@ jobs:
530
556
  name: Deploy the final (deploy-tag-fast)
531
557
  needs: release
532
558
  if: needs.release.outputs.deploy-tag != ''
533
- 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).
534
560
  environment: production # EDIT: the GitHub environment holding your deploy secrets, or remove.
535
561
  permissions:
536
562
  contents: read # check out the tag
@@ -570,3 +596,23 @@ jobs:
570
596
  fi
571
597
  sleep 10
572
598
  done
599
+
600
+ # ON deploy-container.yml (#452): replace the whole `deploy` job above with this one. It calls the
601
+ # same workflow a human-pushed final runs (`push: tags`), so the fast route and route deploy-tag
602
+ # share ONE deploy path — build once, run exactly the tag, verify release.health-url, roll back.
603
+ # Commented because a live `uses:` of a file your repo does not have breaks this workflow.
604
+ # A reusable workflow's permissions are capped by the calling job's, hence the three below.
605
+ #
606
+ # deploy:
607
+ # name: Deploy the final (deploy-tag-fast)
608
+ # needs: release
609
+ # if: needs.release.outputs.deploy-tag != ''
610
+ # permissions:
611
+ # contents: read
612
+ # packages: write
613
+ # issues: write
614
+ # uses: ./.github/workflows/deploy-container.yml
615
+ # with:
616
+ # tag: ${{ needs.release.outputs.deploy-tag }}
617
+ # health-url: ${{ needs.release.outputs.health-url }}
618
+ # secrets: inherit
@@ -20,7 +20,7 @@
20
20
  * npm-gate: <command> # #433 — the pack-allowlist gate, run before every npm publish
21
21
  * version-source: tag # #438 — tag | manifest: is a manifest's version checked, or derivable?
22
22
  * final-grant: 123 # #441 — an operator's recorded decision letting deploy-tag's final be automatic
23
- * health-url: https://… # #446 — deploy-tag-fast only: the public endpoint reporting the running version
23
+ * health-url: https://… # #446/#452 — deploy-tag or deploy-tag-fast (required there): the public endpoint reporting the running version
24
24
  * rollback: auto # #446 — deploy-tag-fast only: the deploy rolls itself back when that check fails
25
25
  * final-spacing: 1h # #446 — deploy-tag-fast only: minimum time between finals (<N>h | <N>d, ≥ 1h)
26
26
  *
@@ -67,6 +67,12 @@ const GRANTABLE_ROW = 'released-tag';
67
67
  const FAST_ROUTE = 'deploy-tag-fast';
68
68
  const GRANTABLE_ROUTES = Object.freeze([GRANTABLE_ROUTE, FAST_ROUTE]);
69
69
  const FAST_KEYS = Object.freeze(['health-url', 'rollback', 'final-spacing']);
70
+ // #452: `health-url` is the one verify key every deploy shares — #446's health gate and the container
71
+ // deploy template's verify step (templates/deploy-container.yml) read the same line. It is legal on
72
+ // both deploying-tag routes and required only on the fast one; `rollback` and `final-spacing` stay
73
+ // the fast route's alone.
74
+ const FAST_ONLY_KEYS = Object.freeze(['rollback', 'final-spacing']);
75
+ const HEALTH_URL_ROUTES = Object.freeze([GRANTABLE_ROUTE, FAST_ROUTE]);
70
76
  const ROLLBACK = Object.freeze(['auto']);
71
77
  // The minimum spacing between two finals on deploy-tag-fast: both the default and the floor. A burst
72
78
  // of merges then deploys at most once an hour; a repo may lengthen it, never shorten it.
@@ -168,7 +174,7 @@ function deriveDefault(cfg) {
168
174
  /** A route's policy as an effective-shaped object (no `why`). */
169
175
  function routePolicy(route) {
170
176
  const p = ROUTE_POLICY[route];
171
- return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: 'manifest', finalGrant: null, healthGate: null, finalSpacingHours: null } : null;
177
+ return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: 'manifest', finalGrant: null, healthGate: null, healthUrl: null, finalSpacingHours: null } : null;
172
178
  }
173
179
 
174
180
  /** `6h` -> 6, `2d` -> 48; anything else (including `30m`, `0h`) -> null. */
@@ -221,7 +227,7 @@ function evaluateRelease(cfg) {
221
227
  const fromDerived = () => ({
222
228
  route: derived.route, candidates: derived.candidates, candidatesPerDay: derived.candidatesPerDay,
223
229
  testPeriodDays: derived.testPeriodDays, final: derived.final, finalize: derived.finalize, npm: null,
224
- versionSource: 'manifest', finalGrant: null, healthGate: null, finalSpacingHours: null,
230
+ versionSource: 'manifest', finalGrant: null, healthGate: null, healthUrl: null, finalSpacingHours: null,
225
231
  });
226
232
  let effective = fromDerived();
227
233
  const findings = [];
@@ -359,10 +365,19 @@ function evaluateRelease(cfg) {
359
365
  else effective.versionSource = v;
360
366
  }
361
367
 
362
- // #446: the fast route's own keys — only there, and the floor on spacing.
363
- const fastKeys = FAST_KEYS.filter((k) => k in raw);
368
+ // #446: the fast route's own keys — only there, and the floor on spacing. #452: `health-url` is
369
+ // shared with deploy-tag, where it is optional and only names the version a deploy waits for.
370
+ const fastKeys = FAST_ONLY_KEYS.filter((k) => k in raw);
371
+ if ('health-url' in raw && effective.route === GRANTABLE_ROUTE) {
372
+ if (!validHealthUrl(raw['health-url'])) fail(`release.health-url is ${JSON.stringify(raw['health-url'])}, expected an absolute https:// URL that reports the running version`);
373
+ else effective.healthUrl = raw['health-url'].trim();
374
+ } else if ('health-url' in raw && effective.route !== FAST_ROUTE && raw.route !== FAST_ROUTE) {
375
+ fail(`release.health-url fits only route ${HEALTH_URL_ROUTES.join(' or ')} — ${route} on ${derived.axis} is not that (${routes}). ` +
376
+ 'Nothing deploys from a tag here, so there is no running version to check. Remove the key');
377
+ }
364
378
  if (effective.route === FAST_ROUTE) {
365
379
  effective.healthGate = { url: raw['health-url'].trim(), rollback: raw.rollback };
380
+ effective.healthUrl = raw['health-url'].trim();
366
381
  effective.finalSpacingHours = FINAL_SPACING_HOURS;
367
382
  if ('final-spacing' in raw) {
368
383
  const h = parseSpacing(raw['final-spacing']);
@@ -425,7 +440,7 @@ function finalGrantVerdict(record, { issue, trust } = {}) {
425
440
  }
426
441
 
427
442
  module.exports = {
428
- VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW, GRANTABLE_ROUTES, FAST_ROUTE, FAST_KEYS, ROLLBACK, FINAL_SPACING_HOURS,
443
+ VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW, GRANTABLE_ROUTES, FAST_ROUTE, FAST_KEYS, FAST_ONLY_KEYS, HEALTH_URL_ROUTES, ROLLBACK, FINAL_SPACING_HOURS,
429
444
  parseGrantIssue, finalGrantVerdict, parseSpacing, validHealthUrl, fastRoutePrerequisites,
430
445
  KEYS, INPUT_KEYS, NPM_KEYS, NPM_ROUTES, CANDIDATES, FINAL, TEST_PERIOD_DAYS, ROUTES, ROUTE_POLICY, ROW_ROUTES,
431
446
  deriveDefault, evaluateRelease, parseTestPeriod, routePolicy,
@@ -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 };
@@ -479,6 +479,7 @@ const WORKFLOW_FINGERPRINTS = [
479
479
  { marker: 'Release (auto) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'release-auto' },
480
480
  { marker: 'Deploy (SSH/rsync to shared hosting) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'deploy-xserver' },
481
481
  { marker: 'Branch name — TEMPLATE. Copy me into your repo', kind: 'text', template: 'branch-name' },
482
+ { marker: 'Deploy (container, platform adapter) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'deploy-container' },
482
483
  // The header convention itself, unattributed: this catches a copy of any template ADDED LATER
483
484
  // without anyone remembering to extend this list — provided the new template keeps the house
484
485
  // header. A template that omits it is invisible here, which is worth knowing when writing one.
@@ -503,6 +504,10 @@ const WORKFLOW_FINGERPRINTS = [
503
504
  // overwrite. Verified against all three before being added here.
504
505
  { marker: 'Resolve deploy toolchain', kind: 'step', template: 'deploy-xserver' },
505
506
  { marker: 'Verify the deployed site answers', kind: 'step', template: 'deploy-xserver' },
507
+ // deploy-container (#452): its one coined step. "Resolve the tag to deploy" is deliberately not a
508
+ // marker — a phrase a hand-written deploy workflow could carry, and an over-eager marker invites
509
+ // an overwrite.
510
+ { marker: 'Build once, run exactly this tag, verify (deploy-container-run)', kind: 'step', template: 'deploy-container' },
506
511
  // branch-name (#348): its one step.
507
512
  { marker: 'Check branch name (CONVENTIONS §4)', kind: 'step', template: 'branch-name' },
508
513
  // Shared by all three ci-* templates: proves derivation, cannot say from which. Note the exact