@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10

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.
Files changed (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1902 -278
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +723 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +778 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +324 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
@@ -0,0 +1,368 @@
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
+ // DEPLOY_BUILD_ARGS optional, one build arg per line: `KEY=VALUE` for every image, or
23
+ // `<image-ref> KEY=VALUE` for one. A value may use ${TAG} (vX.Y.Z),
24
+ // ${VERSION} (X.Y.Z) and ${SHA} (the tag's commit) — substituted here,
25
+ // not by a shell. Build args are baked into the image: never a secret.
26
+ // PRE_DEPLOY optional shell command; gets TAG and PREVIOUS_TAG in its env
27
+ // HEALTH_URL the version URL; else --health-url; else release.health-url in
28
+ // .github/project.yml
29
+ // HEALTH_AUTH_HEADER optional, `Name: value` sent with every version-URL request — or
30
+ // HEALTH_BASIC_AUTH optional, `user:password` sent as HTTP Basic. From a secret; masked
31
+ // in the log and never printed. Set at most one.
32
+ // VERIFY_TIMEOUT_SECONDS 600 · POLL_INTERVAL_MS 5000 · DEPLOY_TIMEOUT_SECONDS 600 ·
33
+ // BUSY_TIMEOUT_SECONDS 600
34
+ // GH_TOKEN, GITHUB_REPOSITORY — to record on the release issue (optional)
35
+ //
36
+ // Usage: node deploy-container-run.mjs --tag vX.Y.Z [--health-url URL] [--tag-sha SHA]
37
+ // [--publish-only | --deploy-only]
38
+ // --publish-only step 1 alone: build and push every image, then stop. Needs no platform
39
+ // configuration and no version URL — so a final publishes its images even
40
+ // before the platform is switched on (the workflow's ungated `publish` job).
41
+ // --deploy-only steps 2-5 alone: every image must already be in the registry for the tag
42
+ // (the `publish` job pushed it); a missing one fails before the platform is
43
+ // touched, never a rebuild here.
44
+ // Exit: 0 = running vX.Y.Z, verified (or, --publish-only, every image pushed) · 1 = not deployed
45
+ // (rolled back where something changed).
46
+
47
+ import { spawnSync } from 'node:child_process';
48
+ import fs from 'node:fs';
49
+ import { fileURLToPath } from 'node:url';
50
+
51
+ const FINAL_TAG = /^v(\d+)\.(\d+)\.(\d+)$/;
52
+
53
+ /** `<ref> <context> [<dockerfile>]` per line; blank lines and `#` comments skipped. */
54
+ export function parseImages(text) {
55
+ const out = [];
56
+ for (const raw of String(text || '').split('\n')) {
57
+ const line = raw.replace(/#.*$/, '').trim();
58
+ if (!line) continue;
59
+ const [ref, context, dockerfile] = line.split(/\s+/);
60
+ if (!ref || !context) throw new Error(`DEPLOY_IMAGES line "${line}" needs <image-ref> <build-context> [<dockerfile>]`);
61
+ 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`);
62
+ out.push({ ref, context, dockerfile: dockerfile || `${context.replace(/\/+$/, '')}/Dockerfile` });
63
+ }
64
+ return out;
65
+ }
66
+
67
+ /**
68
+ * DEPLOY_BUILD_ARGS → per-image `--build-arg` lists. `KEY=VALUE` applies to every image,
69
+ * `<image-ref> KEY=VALUE` to that one (a later line for the same key wins, per-image over shared).
70
+ * ${TAG} / ${VERSION} / ${SHA} are substituted; any other ${NAME} is a typo and refused.
71
+ */
72
+ export function parseBuildArgs(text, images, release) {
73
+ const vars = { TAG: release.tag, VERSION: String(release.tag).replace(/^v/, ''), SHA: release.sha };
74
+ const refs = new Set(images.map((i) => i.ref));
75
+ const shared = new Map();
76
+ const per = new Map(images.map((i) => [i.ref, new Map()]));
77
+ for (const raw of String(text || '').split('\n')) {
78
+ const line = raw.trim();
79
+ if (!line || line.startsWith('#')) continue;
80
+ let target = null; let pair = line;
81
+ const first = line.split(/\s+/, 1)[0];
82
+ if (!first.includes('=')) {
83
+ target = first;
84
+ pair = line.slice(first.length).trim();
85
+ if (!refs.has(target)) throw new Error(`DEPLOY_BUILD_ARGS line "${line}" names ${target}, which DEPLOY_IMAGES does not list`);
86
+ }
87
+ const m = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(pair);
88
+ if (!m) throw new Error(`DEPLOY_BUILD_ARGS line "${line}" needs KEY=VALUE or <image-ref> KEY=VALUE`);
89
+ const value = m[2].replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, k) => {
90
+ if (!(k in vars)) throw new Error(`DEPLOY_BUILD_ARGS: \${${k}} is not one of \${TAG}, \${VERSION}, \${SHA}`);
91
+ return vars[k];
92
+ });
93
+ (target ? per.get(target) : shared).set(m[1], value);
94
+ }
95
+ const out = {};
96
+ for (const img of images) {
97
+ const merged = new Map([...shared, ...per.get(img.ref)]);
98
+ out[img.ref] = [...merged].flatMap(([k, v]) => ['--build-arg', `${k}=${v}`]);
99
+ }
100
+ return out;
101
+ }
102
+
103
+ /** HEALTH_AUTH_HEADER / HEALTH_BASIC_AUTH → { headers, secret }; the secret is what to mask. */
104
+ export function healthAuth(env) {
105
+ const header = (env.HEALTH_AUTH_HEADER || '').trim();
106
+ const basic = env.HEALTH_BASIC_AUTH || '';
107
+ if (header && basic) throw new Error('set HEALTH_AUTH_HEADER or HEALTH_BASIC_AUTH, not both');
108
+ if (basic) {
109
+ if (!basic.includes(':')) throw new Error('HEALTH_BASIC_AUTH must be user:password');
110
+ const token = Buffer.from(basic, 'utf8').toString('base64');
111
+ return { headers: { Authorization: `Basic ${token}` }, secrets: [basic, token] };
112
+ }
113
+ if (header) {
114
+ const m = /^([A-Za-z0-9-]+):\s*(.+)$/.exec(header);
115
+ if (!m) throw new Error('HEALTH_AUTH_HEADER must be "Name: value"');
116
+ return { headers: { [m[1]]: m[2] }, secrets: [m[2]] };
117
+ }
118
+ return { headers: {}, secrets: [] };
119
+ }
120
+
121
+ /** Does `body` report `version` — as a whole version, so 1.2.1 never matches 1.2.10 or 11.2.1? */
122
+ export function reportsVersion(body, version) {
123
+ const v = String(version).replace(/^v/, '').replace(/\./g, '\\.');
124
+ return new RegExp(`(?<![0-9.])v?${v}(?![0-9]|\\.[0-9])`).test(String(body || ''));
125
+ }
126
+
127
+ /** release.health-url from a project.yml text — block style only; anything else reads as absent. */
128
+ export function readHealthUrl(text) {
129
+ const lines = String(text || '').split('\n');
130
+ const at = lines.findIndex((l) => /^release:\s*(#.*)?$/.test(l));
131
+ if (at < 0) return null;
132
+ for (let i = at + 1; i < lines.length; i++) {
133
+ const l = lines[i];
134
+ if (l.trim() && !/^\s/.test(l)) break;
135
+ const m = /^\s+health-url:\s*["']?([^"'\s#]+)["']?\s*(#.*)?$/.exec(l);
136
+ if (m) return m[1];
137
+ }
138
+ return null;
139
+ }
140
+
141
+ /** The newest strict final tag (vN.N.N, no pre-release) below `current`, or null. */
142
+ export function previousFinalTag(tags, current) {
143
+ const key = (t) => { const m = FINAL_TAG.exec(t); return m ? [+m[1], +m[2], +m[3]] : null; };
144
+ const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
145
+ const cur = key(current);
146
+ const older = (tags || []).map((t) => [t, key(t)]).filter(([, k]) => k && (!cur || cmp(k, cur) < 0));
147
+ older.sort((a, b) => cmp(b[1], a[1]));
148
+ return older.length ? older[0][0] : null;
149
+ }
150
+
151
+ export async function loadAdapter(name) {
152
+ if (!/^[a-z0-9-]+$/.test(name)) throw new Error(`DEPLOY_ADAPTER "${name}" is not an adapter name`);
153
+ return import(new URL(`./deploy-adapter-${name}.mjs`, import.meta.url));
154
+ }
155
+
156
+ function sh(cmd, args, opts = {}) {
157
+ const r = spawnSync(cmd, args, { encoding: 'utf8', stdio: opts.inherit ? 'inherit' : 'pipe', env: opts.env || process.env });
158
+ return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
159
+ }
160
+
161
+ function defaultIo(env) {
162
+ return {
163
+ env,
164
+ fetch: globalThis.fetch,
165
+ sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
166
+ now: () => Date.now(),
167
+ log: (m) => console.log(m),
168
+ mask: (v) => { if (env.GITHUB_ACTIONS) console.log(`::add-mask::${v}`); },
169
+ error: (m) => console.log(`::error::${m}`),
170
+ sh,
171
+ summary: (line) => { if (env.GITHUB_STEP_SUMMARY) fs.appendFileSync(env.GITHUB_STEP_SUMMARY, `${line}\n`); },
172
+ readFile: (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } },
173
+ };
174
+ }
175
+
176
+ async function waitForVersion(url, version, io, timeoutS, auth = {}) {
177
+ const until = io.now() + timeoutS * 1000;
178
+ let last = '';
179
+ for (;;) {
180
+ try {
181
+ const res = await io.fetch(url, { headers: { 'Cache-Control': 'no-cache', ...auth } });
182
+ last = await res.text();
183
+ if (res.ok && reportsVersion(last, version)) return true;
184
+ } catch (e) { last = String(e && e.message); }
185
+ if (io.now() >= until) return false;
186
+ await io.sleep(io.timing.pollMs);
187
+ }
188
+ }
189
+
190
+ function record(io, tag, line) {
191
+ io.summary(line);
192
+ const repo = io.env.GITHUB_REPOSITORY;
193
+ if (!repo) return;
194
+ const found = io.sh('gh', ['issue', 'list', '--repo', repo, '--state', 'all', '--search', `"colab:release version=${tag}" in:body`, '--json', 'number', '--jq', '.[0].number // ""']);
195
+ const n = found.status === 0 ? found.stdout.trim() : '';
196
+ if (!n) { io.log(`no release issue for ${tag} — recorded in the run summary only`); return; }
197
+ const c = io.sh('gh', ['issue', 'comment', n, '--repo', repo, '--body', line]);
198
+ if (c.status !== 0) io.log(`could not comment on release issue #${n}: ${c.stderr.trim()}`);
199
+ }
200
+
201
+ function buildOnce(images, tag, sha, io, buildArgs = {}) {
202
+ for (const img of images) {
203
+ if (io.sh('docker', ['manifest', 'inspect', `${img.ref}:${tag}`]).status === 0) {
204
+ io.log(`${img.ref}:${tag} is already pushed — built once per tag, not rebuilt`);
205
+ continue;
206
+ }
207
+ const steps = [
208
+ ['build', '-f', img.dockerfile, ...(buildArgs[img.ref] || []), '-t', `${img.ref}:${tag}`, '-t', `${img.ref}:${sha}`, img.context],
209
+ ['push', `${img.ref}:${tag}`],
210
+ ['push', `${img.ref}:${sha}`],
211
+ ];
212
+ for (const args of steps) {
213
+ const r = io.sh('docker', args, { inherit: true });
214
+ if (r.status !== 0) throw new Error(`docker ${args[0]} ${img.ref} failed (exit ${r.status})`);
215
+ }
216
+ }
217
+ }
218
+
219
+ /** The whole contract. Returns the exit code. */
220
+ export async function run(opts, io) {
221
+ const env = io.env;
222
+ const tag = opts.tag;
223
+ const fail = (m) => { io.error(m); return 1; };
224
+ if (opts.publishOnly && opts.deployOnly) return fail('--publish-only and --deploy-only together would do nothing — pass at most one');
225
+ if (!FINAL_TAG.test(tag || '')) return fail(`"${tag}" is not a final tag vX.Y.Z — this deploys finals only`);
226
+ const version = tag.slice(1);
227
+ const healthUrl = opts.publishOnly ? null : opts.healthUrl || env.HEALTH_URL || readHealthUrl(io.readFile('.github/project.yml'));
228
+ if (!opts.publishOnly && !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');
229
+
230
+ let images; let adapter; let cfg; let auth = {};
231
+ try {
232
+ images = parseImages(env.DEPLOY_IMAGES);
233
+ if (!images.length) throw new Error('DEPLOY_IMAGES lists no image — list every image this stack runs');
234
+ if (!opts.publishOnly) {
235
+ const a = healthAuth(env);
236
+ for (const s of a.secrets) if (io.mask) io.mask(s);
237
+ auth = a.headers;
238
+ adapter = await loadAdapter(env.DEPLOY_ADAPTER || 'portainer');
239
+ cfg = adapter.configFromEnv(env);
240
+ }
241
+ } catch (e) { return fail(e.message); }
242
+
243
+ const tagSha = opts.tagSha || io.sh('git', ['rev-parse', `${tag}^{commit}`]).stdout.trim();
244
+ if (!/^[0-9a-f]{40}$/.test(tagSha)) return fail(`could not resolve ${tag} to a commit`);
245
+ const at = () => new Date(io.now()).toISOString();
246
+
247
+ // 1. Build once — or, --deploy-only, check the publish job left every image in the registry.
248
+ if (opts.deployOnly) {
249
+ const missing = images.filter((img) => io.sh('docker', ['manifest', 'inspect', `${img.ref}:${tag}`]).status !== 0).map((img) => `${img.ref}:${tag}`);
250
+ if (missing.length) {
251
+ const m = `not in the registry: ${missing.join(', ')} — the publish job pushes every image before the deploy; nothing deployed`;
252
+ record(io, tag, `deploy of ${tag} failed at ${at()}: ${m}`);
253
+ return fail(m);
254
+ }
255
+ } else {
256
+ let buildArgs;
257
+ try { buildArgs = parseBuildArgs(env.DEPLOY_BUILD_ARGS, images, { tag, sha: tagSha }); } catch (e) { return fail(e.message); }
258
+ try { buildOnce(images, tag, tagSha, io, buildArgs); } catch (e) {
259
+ const what = opts.publishOnly ? 'publish' : 'deploy';
260
+ if (opts.publishOnly) io.summary(`${what} of ${tag} failed at ${at()}: ${e.message}`);
261
+ else record(io, tag, `${what} of ${tag} failed at ${at()}: ${e.message} — nothing deployed`);
262
+ return fail(e.message);
263
+ }
264
+ if (opts.publishOnly) {
265
+ const line = `published ${tag} at ${at()} — ${images.map((i) => `${i.ref}:${tag}`).join(', ')}`;
266
+ io.log(line);
267
+ io.summary(line);
268
+ return 0;
269
+ }
270
+ }
271
+ const tags = io.sh('git', ['tag', '--list', 'v*']).stdout.split('\n').map((t) => t.trim()).filter(Boolean);
272
+ const previous = previousFinalTag(tags, tag);
273
+
274
+ // 2. Pre-deploy hook — before anything on the platform changes.
275
+ if (env.PRE_DEPLOY && env.PRE_DEPLOY.trim()) {
276
+ const r = io.sh('sh', ['-c', env.PRE_DEPLOY], { inherit: true, env: { ...env, TAG: tag, PREVIOUS_TAG: previous || '' } });
277
+ if (r.status !== 0) {
278
+ record(io, tag, `deploy of ${tag} stopped at ${at()}: the pre-deploy hook failed (exit ${r.status}) — nothing deployed`);
279
+ return fail(`pre-deploy hook failed (exit ${r.status}) — the platform was not called`);
280
+ }
281
+ }
282
+
283
+ // 3. Snapshot, then run exactly this tag.
284
+ const refs = images.map((i) => i.ref);
285
+ let snap;
286
+ try { snap = await adapter.snapshot(cfg, io); } catch (e) {
287
+ record(io, tag, `deploy of ${tag} failed at ${at()}: ${e.message} — nothing deployed`);
288
+ return fail(e.message);
289
+ }
290
+ const fileContent = cfg.kind === 'file' ? io.readFile(cfg.composeFile) : undefined;
291
+ if (cfg.kind === 'file' && fileContent === null) return fail(`compose file ${cfg.composeFile} not found in the checkout`);
292
+
293
+ let reason = null;
294
+ try {
295
+ await adapter.deploy(cfg, { tag, tagSha, images: refs, fileContent }, io, snap);
296
+ if (!(await waitForVersion(healthUrl, version, io, io.timing.verifyTimeoutS, auth))) {
297
+ throw Object.assign(new Error(`${healthUrl} did not report ${version} within ${io.timing.verifyTimeoutS}s`), { changed: true });
298
+ }
299
+ } catch (e) {
300
+ reason = e;
301
+ }
302
+ if (!reason) {
303
+ const line = `running ${tag} at ${at()} — ${healthUrl} reports ${version}`;
304
+ io.log(line);
305
+ record(io, tag, line);
306
+ return 0;
307
+ }
308
+ if (!reason.changed) {
309
+ record(io, tag, `deploy of ${tag} failed at ${at()}: ${reason.message}`);
310
+ return fail(reason.message);
311
+ }
312
+
313
+ // 4. Roll back: what ran before, when it was a final; else the previous final tag.
314
+ const snapTag = snap.ref && /^refs\/tags\//.test(snap.ref) ? snap.ref.slice('refs/tags/'.length) : null;
315
+ const envTag = ((snap.env || []).find((e) => e.name === 'IMAGE_TAG') || {}).value || null;
316
+ const backTag = [snapTag, envTag].find((t) => t && FINAL_TAG.test(t)) || null;
317
+ let back = null; let verified = false;
318
+ try {
319
+ if (backTag) {
320
+ back = backTag;
321
+ await adapter.restore(cfg, snap, io, { tag: backTag, images: refs });
322
+ } else if (previous) {
323
+ back = previous;
324
+ const prevSha = io.sh('git', ['rev-parse', `${previous}^{commit}`]).stdout.trim();
325
+ await adapter.deploy(cfg, { tag: previous, tagSha: prevSha, images: refs, fileContent: snap.fileContent }, io, snap);
326
+ }
327
+ if (back) verified = await waitForVersion(healthUrl, back.slice(1), io, io.timing.verifyTimeoutS, auth);
328
+ } catch (e) {
329
+ io.log(`rollback to ${back} failed: ${e.message}`);
330
+ }
331
+ const line = back
332
+ ? `deploy of ${tag} failed at ${at()}: ${reason.message}; rolled back to ${back} (${verified ? 'verified' : 'NOT verified'})`
333
+ : `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`;
334
+ record(io, tag, line);
335
+ return fail(line);
336
+ }
337
+
338
+ export function parseArgs(argv) {
339
+ const o = {};
340
+ for (let i = 0; i < argv.length; i++) {
341
+ const a = argv[i];
342
+ if (a === '--publish-only') { o.publishOnly = true; continue; }
343
+ if (a === '--deploy-only') { o.deployOnly = true; continue; }
344
+ const m = /^--([a-z-]+)(?:=(.*))?$/.exec(a);
345
+ if (!m) continue;
346
+ const v = m[2] !== undefined ? m[2] : argv[++i];
347
+ if (m[1] === 'tag') o.tag = v;
348
+ else if (m[1] === 'health-url') o.healthUrl = v;
349
+ else if (m[1] === 'tag-sha') o.tagSha = v;
350
+ }
351
+ return o;
352
+ }
353
+
354
+ if (process.argv[1] && fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1])) {
355
+ const env = process.env;
356
+ const io = defaultIo(env);
357
+ const num = (k, d) => (Number(env[k]) > 0 ? Number(env[k]) : d);
358
+ io.timing = {
359
+ pollMs: num('POLL_INTERVAL_MS', 5000),
360
+ deployTimeoutS: num('DEPLOY_TIMEOUT_SECONDS', 600),
361
+ busyTimeoutS: num('BUSY_TIMEOUT_SECONDS', 600),
362
+ verifyTimeoutS: num('VERIFY_TIMEOUT_SECONDS', 600),
363
+ };
364
+ run(parseArgs(process.argv.slice(2)), io).then((code) => process.exit(code), (e) => {
365
+ console.log(`::error::${e && e.stack ? e.stack : e}`);
366
+ process.exit(1);
367
+ });
368
+ }
@@ -0,0 +1,219 @@
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
+ # - `secrets.HEALTH_AUTH_HEADER` (`Name: value`) or `secrets.HEALTH_BASIC_AUTH` (`user:password`)
47
+ # — optional, only when the version URL sits behind auth. Masked; never printed.
48
+ # Everything else is configuration: the workflow-level `env` (images, build args — both jobs read
49
+ # them) and the env block of the deploy job's last step (the platform).
50
+ #
51
+ # TWO JOBS (#460). `publish` builds and pushes every image on EVERY final, whatever the platform's
52
+ # state — so a repo not yet cut over still has each final's image in the registry, ready to stage.
53
+ # `deploy` needs it and only talks to the platform; it never builds (a missing image fails before
54
+ # the platform is touched). Gate `deploy`, never `publish`, on "is the platform switched on".
55
+ #
56
+ # TOPOLOGY. Every server runs its own Portainer — there is no central panel and no Portainer
57
+ # Agent. So the per-app configuration is THAT host's Portainer URL + endpointId + stack id + key.
58
+ # Hosts are named by DNS name, never by address. The runner reaches the platform directly on the
59
+ # LAN or over a VPN — this file does not care which, as long as `runs-on` is a runner that can.
60
+ #
61
+ # EVERY REDEPLOY RECREATES THE CONTAINERS, even when the compose file did not change (measured on
62
+ # Portainer CE 2.45.1) — expect a short restart on every deploy, a rollback included.
63
+ #
64
+ # YOUR COMPOSE FILE names each image as `<image-ref>:${IMAGE_TAG}`. The adapter sets IMAGE_TAG in
65
+ # the stack's environment and sends the WHOLE current environment back — the platform replaces the
66
+ # list wholesale, so a partial list would delete your other variables.
67
+
68
+ name: Deploy (container)
69
+
70
+ on:
71
+ push:
72
+ tags: ["v*.*.*", "!v*.*.*-*"] # finals only — a candidate vX.Y.Z-rc.N never deploys
73
+ workflow_dispatch:
74
+ inputs:
75
+ tag:
76
+ description: "Final tag to deploy (vX.Y.Z) — the previous one rolls back by hand"
77
+ required: true
78
+ type: string
79
+ workflow_call:
80
+ inputs:
81
+ tag:
82
+ description: "Final tag to deploy (vX.Y.Z)"
83
+ required: true
84
+ type: string
85
+ health-url:
86
+ description: "Version URL (release.health-url); read from .github/project.yml when empty"
87
+ required: false
88
+ type: string
89
+ default: ""
90
+ secrets:
91
+ PORTAINER_API_KEY:
92
+ required: false
93
+ REGISTRY_PASSWORD:
94
+ required: false
95
+ HEALTH_AUTH_HEADER:
96
+ required: false
97
+ HEALTH_BASIC_AUTH:
98
+ required: false
99
+
100
+ # One deploy at a time per repo, never cancelled half-way: a cancelled deploy is a stack in an
101
+ # unknown state. A fixed group, because under workflow_call `github.workflow` is the CALLER's name.
102
+ concurrency:
103
+ group: deploy-container-${{ github.repository }}
104
+ cancel-in-progress: false
105
+
106
+ permissions:
107
+ contents: read
108
+
109
+ # Read by both jobs. Workflow-level, so the list is written once: `publish` builds exactly what
110
+ # `deploy` then checks is in the registry.
111
+ env:
112
+ # EDIT: every image this stack runs, one per line: <image-ref> <build-context> [<dockerfile>].
113
+ DEPLOY_IMAGES: |
114
+ ghcr.io/${{ github.repository }} .
115
+ # EDIT: optional build args, one per line — `KEY=VALUE` for every image, `<image-ref> KEY=VALUE`
116
+ # for one. ${TAG} (vX.Y.Z), ${VERSION} (X.Y.Z) and ${SHA} (the tag's commit) are filled in by the
117
+ # driver. Baked into the image, so public values only (`vars.*`), never a secret.
118
+ DEPLOY_BUILD_ARGS: ""
119
+
120
+ jobs:
121
+ publish:
122
+ name: Publish the final's images
123
+ # Never gated on the platform: a final publishes its images before cutover too.
124
+ runs-on: ubuntu-latest # EDIT: a runner with docker.
125
+ permissions:
126
+ contents: read # check out the tag
127
+ packages: write # push the images (GHCR); drop it for another registry
128
+ timeout-minutes: 45
129
+ outputs:
130
+ tag: ${{ steps.tag.outputs.tag }}
131
+ steps:
132
+ - name: Resolve the tag to deploy
133
+ id: tag
134
+ env:
135
+ INPUT_TAG: ${{ inputs.tag }}
136
+ run: |
137
+ set -euo pipefail
138
+ TAG="${INPUT_TAG:-$GITHUB_REF_NAME}"
139
+ if ! printf '%s' "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
140
+ echo "::error::\"$TAG\" is not a final tag vX.Y.Z — a candidate (-rc.N) or a branch never deploys"
141
+ exit 1
142
+ fi
143
+ echo "tag=$TAG" >> "$GITHUB_OUTPUT"
144
+
145
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
146
+ with:
147
+ ref: refs/tags/${{ steps.tag.outputs.tag }} # the tag ref resolves to the commit it builds
148
+ persist-credentials: false # nothing here pushes to git
149
+
150
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
151
+ with:
152
+ node-version: "22"
153
+
154
+ - name: Log in to the image registry
155
+ env:
156
+ REGISTRY: ghcr.io # EDIT: your registry host
157
+ REGISTRY_USER: ${{ github.actor }} # EDIT: the registry user, when not GHCR
158
+ REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD || github.token }}
159
+ run: |
160
+ set -euo pipefail
161
+ printf '%s' "$REGISTRY_PASSWORD" | docker login "$REGISTRY" -u "$REGISTRY_USER" --password-stdin
162
+
163
+ - name: Build once and push (deploy-container-run --publish-only)
164
+ env:
165
+ TAG: ${{ steps.tag.outputs.tag }}
166
+ run: node .github/deploy/deploy-container-run.mjs --tag "$TAG" --publish-only
167
+
168
+ deploy:
169
+ name: Deploy the final
170
+ needs: publish
171
+ # EDIT: gate the platform half here, e.g. `if: vars.PLATFORM_LIVE == 'true'` — never `publish`.
172
+ runs-on: ubuntu-latest # EDIT: a runner that reaches your platform (LAN or VPN) and has docker.
173
+ environment: production # EDIT: the GitHub environment holding PORTAINER_API_KEY, or remove.
174
+ permissions:
175
+ contents: read # check out the tag
176
+ packages: read # confirm the images are in the registry (GHCR); drop it for another registry
177
+ issues: write # record the outcome on the release issue
178
+ timeout-minutes: 45
179
+ steps:
180
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
181
+ with:
182
+ ref: refs/tags/${{ needs.publish.outputs.tag }}
183
+ fetch-depth: 0 # every tag: the rollback target is the previous final
184
+ persist-credentials: false # nothing here pushes to git
185
+
186
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
187
+ with:
188
+ node-version: "22"
189
+
190
+ - name: Log in to the image registry
191
+ env:
192
+ REGISTRY: ghcr.io # EDIT: your registry host
193
+ REGISTRY_USER: ${{ github.actor }} # EDIT: the registry user, when not GHCR
194
+ REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD || github.token }}
195
+ run: |
196
+ set -euo pipefail
197
+ printf '%s' "$REGISTRY_PASSWORD" | docker login "$REGISTRY" -u "$REGISTRY_USER" --password-stdin
198
+
199
+ - name: Run exactly this tag, verify (deploy-container-run --deploy-only)
200
+ env:
201
+ DEPLOY_ADAPTER: portainer
202
+ # EDIT: optional — runs before the platform is called, with TAG and PREVIOUS_TAG set; a
203
+ # non-zero exit stops the deploy before anything changes (a database snapshot, say).
204
+ PRE_DEPLOY: ""
205
+ PORTAINER_URL: https://portainer.app.example.com # EDIT: this host's own Portainer
206
+ PORTAINER_ENDPOINT_ID: "1" # EDIT
207
+ PORTAINER_STACK_ID: "1" # EDIT
208
+ PORTAINER_STACK_KIND: git # EDIT: git (the stack pulls this repo at the tag) | file
209
+ PORTAINER_COMPOSE_FILE: docker-compose.yml # file stacks only: sent as the stack content
210
+ PORTAINER_API_KEY: ${{ secrets.PORTAINER_API_KEY }}
211
+ HEALTH_URL: ${{ inputs.health-url }} # empty → release.health-url in .github/project.yml
212
+ HEALTH_AUTH_HEADER: ${{ secrets.HEALTH_AUTH_HEADER }} # optional: `Name: value`
213
+ HEALTH_BASIC_AUTH: ${{ secrets.HEALTH_BASIC_AUTH }} # optional: `user:password`
214
+ VERIFY_TIMEOUT_SECONDS: "600" # EDIT: how long the new version may take to report itself
215
+ DEPLOY_TIMEOUT_SECONDS: "600"
216
+ BUSY_TIMEOUT_SECONDS: "600"
217
+ GH_TOKEN: ${{ github.token }}
218
+ TAG: ${{ needs.publish.outputs.tag }}
219
+ run: node .github/deploy/deploy-container-run.mjs --tag "$TAG" --deploy-only
@@ -25,6 +25,12 @@
25
25
  # <os>-<arch> is Node's own `${process.platform}-${process.arch}` (darwin-arm64, linux-x64,
26
26
  # win32-x64, …) — the same names npm's `os`/`cpu` fields use, and what the launcher computes.
27
27
  #
28
+ # A PREBUILT JS APP (one whose build cannot run on the target, #470) uses the same workflow with
29
+ # the platform-neutral name `any`: `platforms: any`, `bin: <tool>.tgz`, and an artifact
30
+ # `<artifact-prefix>any` holding that one tarball (`tar -czf <tool>.tgz -C <build-output> .`).
31
+ # templates/npx-service.mjs with KIND 'dist' fetches refs/tags/dist/vX.Y.Z/any, verifies the
32
+ # tarball against its SHA256SUMS and unpacks it beside the running version.
33
+ #
28
34
  # HOW TO CALL IT — from the SAME run that cut the release tag. A tag pushed with GITHUB_TOKEN
29
35
  # triggers no other workflow, so "build on the tag push" silently never runs for a tag your
30
36
  # release workflow made (CONVENTIONS.md §6). Build every platform in that run, upload one
@@ -71,7 +71,7 @@
71
71
  // - a git-IGNORED markdown file is not part of the doc graph and is never
72
72
  // enumerated by any check. Scratch that never ships must not be able to
73
73
  // fail a structural check on the repo — and it was: `.claude/plans/
74
- // issue-<N>.md`, the git-excluded, `code-ship`-deleted plan file that
74
+ // issue-<N>.md` (since #488 `.plans/issue-<N>.md`), the git-excluded, `code-ship`-deleted plan file that
75
75
  // `code-start` writes, contributed 7 of one control run's 10 check-6
76
76
  // failures purely by quoting `§4` in prose, which made the repo lint clean
77
77
  // or dirty depending on who happened to have a session open