@futurelastic/colab-handbook 1.12.0-rc.21 → 1.12.0-rc.22
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 +25 -0
- package/package.json +1 -1
- package/templates/README.md +6 -0
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +268 -0
- package/templates/deploy-container.yml +161 -0
- package/templates/release-auto.yml +24 -1
- package/tools/lib/release-policy.js +21 -6
- package/tools/lib/stamp.js +5 -0
package/audit/audit.mjs
CHANGED
|
@@ -1647,6 +1647,7 @@ function auditRepo(target, ctx) {
|
|
|
1647
1647
|
checkPrereleaseTagTrigger(src, workflows, deploy, fail, warn);
|
|
1648
1648
|
checkReleaseAuto(src, workflows, cfg, warn);
|
|
1649
1649
|
checkFastRouteDeploy(src, workflows, cfg, fail);
|
|
1650
|
+
checkDeployContainer(src, workflows, cfg, warn);
|
|
1650
1651
|
checkPrivateNpm(src, workflows, fail, warn);
|
|
1651
1652
|
|
|
1652
1653
|
const runbook = cfg && "runbook" in cfg ? cfg.runbook : null;
|
|
@@ -2603,6 +2604,30 @@ function checkFastRouteDeploy(src, workflows, cfg, fail) {
|
|
|
2603
2604
|
for (const text of fastRouteDeployFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) fail(text);
|
|
2604
2605
|
}
|
|
2605
2606
|
|
|
2607
|
+
// ---- a deploy-container copy needs a version to wait for (#452) ---------------------------------
|
|
2608
|
+
// templates/deploy-container.yml is green only on a verified running version, read from
|
|
2609
|
+
// release.health-url (or a HEALTH_URL the repo set in its own copy). A copy with neither fails every
|
|
2610
|
+
// deploy at its first step — advisory, not a failure: the repo owns the file, and may have wired
|
|
2611
|
+
// the URL in by hand.
|
|
2612
|
+
function deployContainerFindings({ readFile, workflows, cfg }) {
|
|
2613
|
+
const effective = cfg ? releasePolicy.evaluateRelease(cfg).effective : null;
|
|
2614
|
+
if (effective && effective.healthUrl) return [];
|
|
2615
|
+
const out = [];
|
|
2616
|
+
for (const wf of workflows || []) {
|
|
2617
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
2618
|
+
if (!text) continue;
|
|
2619
|
+
const stamp = parseWorkflowStamp(text);
|
|
2620
|
+
const isCopy = (stamp && stamp.name === "deploy-container") || /deploy-container-run\.mjs/.test(text);
|
|
2621
|
+
if (!isCopy) continue;
|
|
2622
|
+
if (/^\s*HEALTH_URL:\s*["']?https:\/\//m.test(text)) continue;
|
|
2623
|
+
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)`);
|
|
2624
|
+
}
|
|
2625
|
+
return out;
|
|
2626
|
+
}
|
|
2627
|
+
function checkDeployContainer(src, workflows, cfg, warn) {
|
|
2628
|
+
for (const text of deployContainerFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) warn(text);
|
|
2629
|
+
}
|
|
2630
|
+
|
|
2606
2631
|
// ---- a private repo never publishes to public npm (#432) ---------------------
|
|
2607
2632
|
// Visibility is read from the GitHub API, and only when the repo has an npm surface at all (so an
|
|
2608
2633
|
// npm-free repo costs no API call). Unreadable / no remote → reported as a warn, never passed.
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -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)
|
|
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
|
#
|
|
@@ -570,3 +573,23 @@ jobs:
|
|
|
570
573
|
fi
|
|
571
574
|
sleep 10
|
|
572
575
|
done
|
|
576
|
+
|
|
577
|
+
# ON deploy-container.yml (#452): replace the whole `deploy` job above with this one. It calls the
|
|
578
|
+
# same workflow a human-pushed final runs (`push: tags`), so the fast route and route deploy-tag
|
|
579
|
+
# share ONE deploy path — build once, run exactly the tag, verify release.health-url, roll back.
|
|
580
|
+
# Commented because a live `uses:` of a file your repo does not have breaks this workflow.
|
|
581
|
+
# A reusable workflow's permissions are capped by the calling job's, hence the three below.
|
|
582
|
+
#
|
|
583
|
+
# deploy:
|
|
584
|
+
# name: Deploy the final (deploy-tag-fast)
|
|
585
|
+
# needs: release
|
|
586
|
+
# if: needs.release.outputs.deploy-tag != ''
|
|
587
|
+
# permissions:
|
|
588
|
+
# contents: read
|
|
589
|
+
# packages: write
|
|
590
|
+
# issues: write
|
|
591
|
+
# uses: ./.github/workflows/deploy-container.yml
|
|
592
|
+
# with:
|
|
593
|
+
# tag: ${{ needs.release.outputs.deploy-tag }}
|
|
594
|
+
# health-url: ${{ needs.release.outputs.health-url }}
|
|
595
|
+
# 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
|
|
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
|
-
|
|
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,
|
package/tools/lib/stamp.js
CHANGED
|
@@ -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
|