@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
@@ -24,6 +24,8 @@
24
24
  # any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
25
25
  # project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
26
26
  # comment above that job
27
+ # the cut tagged a FINAL — route deploy + health check (job `deploy`, #446) — see
28
+ # deploy-tag-fast only "DEPLOYING IN THIS RUN" below
27
29
  #
28
30
  # Every decision — whether a candidate is owed, which bump, whether the test period
29
31
  # elapsed clean, whether the final is automatic on this repo at all — is the colab CLI's,
@@ -77,6 +79,35 @@
77
79
  # workflow pushes either — on a `deploy: tag` repo the final is a human act anyway, and
78
80
  # finalize --auto only posts the command for it.
79
81
  #
82
+ # DEPLOYING IN THIS RUN (deploy-tag-fast, #446). On a `deploy: tag` repo whose operator granted
83
+ # route `deploy-tag-fast` (release.final-grant + release.health-url + release.rollback: auto),
84
+ # `colab release cut --auto` tags the FINAL vX.Y.Z on every green main head — no candidate, no
85
+ # test period — and the `deploy` job below deploys that tag in this same run, then polls
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) — 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
91
+ # run still concludes on the `release` job. EDIT: on this route, a cron more frequent than daily
92
+ # tags a head that release.final-spacing held back sooner.
93
+ #
94
+ # DRY RUN ON A FIX BRANCH (#474). This workflow never runs on a branch by itself, so a fix to it
95
+ # (a moved runner label, a HANDBOOK_REF naming a missing branch) had no run to prove it, and the
96
+ # cure rule (CONVENTIONS.md §4) could only refuse it — a human ci-grant was the one door. Dispatch
97
+ # it on the fix branch instead:
98
+ #
99
+ # gh workflow run release-auto.yml --ref <fix-branch> -f dry_run=true
100
+ #
101
+ # (`colab ship` dispatches it for you when a red in this workflow is what stands between the branch
102
+ # and trunk). A dispatch on any ref other than main is ALWAYS dry, input or not. A dry run checks out
103
+ # the branch, runs every step with `--dry` — the same decisions, nothing promoted, tagged, released,
104
+ # pushed or dispatched — and skips only the steps whose names end in `[publish]`. The step
105
+ # "Dry run — nothing is tagged, released or published" runs only then; it is how the cure rule
106
+ # recognises the run. Keep both names as they are: the cure rule matches steps BY NAME, and accepts
107
+ # a dry run only if every step that ran in trunk's red run passed in it and every step it skipped
108
+ # ends in `[publish]`. So a red INSIDE a `[publish]` step, or in the npm or deploy jobs (which never
109
+ # run without a tag), cannot be cured by a dry run — that stays a human ci-grant.
110
+ #
80
111
  # IT READS TAGS AND CREATES TAGS. IT NEVER WRITES A COMMIT. No step here commits; the refs
81
112
  # pushed are the tags `colab release cut` / `colab release finalize` create (annotated, their
82
113
  # checks recorded in the tag message) and — only on a repo granting unattended promotion — the
@@ -88,6 +119,13 @@
88
119
  # failed) is the ordinary output of most runs; it is printed to the run summary as a
89
120
  # warning and the job stays green, so a refusal never paints main red for `colab ship`.
90
121
  # Only a run that produced no verdict at all (a crash, gh unusable, bad flags) fails.
122
+ # A STANDING refusal is still not a failure, but it is not a warning either (#467): one no
123
+ # later run clears by itself — no first final tag, a malformed colab:switch marker, a
124
+ # manifest that disagrees — is an `::error title=Release stalled::` annotation plus a
125
+ # summary banner, and `colab release-status` flags the repo. Still exit 0: a red run here
126
+ # would make main's head not-green and refuse the very ship that clears the stall.
127
+ # Every finalize run that makes no final says why, and lists each open candidate's reason
128
+ # and when its own test period ends (#468).
91
129
  #
92
130
  # THE CLI IGNORES THIS WORKFLOW'S OWN RUNS when it reads CI at a commit (GITHUB_WORKFLOW,
93
131
  # #425) — otherwise its own in-progress run would read as "CI not finished" forever. So
@@ -99,6 +137,26 @@
99
137
  # `npm` job, which sets up its own Node for npm's trusted publishing (EDIT point there for
100
138
  # a package that needs a build). The npm job needs a HANDBOOK_REF that carries #433; an
101
139
  # older CLI gives no npm verdict and nothing is published to npm.
140
+ #
141
+ # RUNNERS — ON A PRIVATE REPO, YOUR OWN (#453). This workflow fires on every green CI run on main,
142
+ # so any of its jobs failing is a failed run at main's head, and `colab ship` reads that as main
143
+ # not green. On a PRIVATE (or internal) repo GitHub-hosted minutes are billed, and when the
144
+ # owner's billing fails GitHub refuses a hosted job before it starts: main goes red, every landing
145
+ # is refused until a human steps in — measured twice in a row on one adopting repo, where this was
146
+ # the only workflow on main still on hosted runners. So:
147
+ # private / internal repo `release`, `npm-record` (and `deploy`, if you enable it) run on the
148
+ # SAME self-hosted label your ci.yml's trunk jobs use. The runner needs
149
+ # git, node, gh and jq on its PATH (GitHub-hosted images have all four).
150
+ # public repo `ubuntu-latest` is fine — hosted minutes are free there.
151
+ # the `npm` job GitHub-hosted on every repo: npm trusted publishing requires it. It only
152
+ # runs on a public repo (a private one is refused outright, #432), so it
153
+ # is never billed.
154
+ # The trade-off, stated: a self-hosted release job queues behind your own runners, and an offline
155
+ # pool delays a candidate — it never paints main red the way a refused hosted job does. The label
156
+ # is a literal EDIT point, not an expression keyed on visibility: `github.event.repository` is not
157
+ # in a scheduled run's payload, so a visibility switch would silently pick hosted on exactly the
158
+ # daily run. `colab audit` flags a private repo whose release workflow still runs hosted, naming
159
+ # the label your other workflows already use.
102
160
 
103
161
  name: Release (auto)
104
162
 
@@ -113,12 +171,21 @@ on:
113
171
  # hour is when scheduled runs queue longest.
114
172
  - cron: "17 3 * * *"
115
173
  workflow_dispatch:
174
+ # #474: a DRY RUN for a fix branch — see "DRY RUN ON A FIX BRANCH" in the header. A dispatch on
175
+ # any ref other than main is dry whether or not this is set; on main it is opt-in.
176
+ inputs:
177
+ dry_run:
178
+ description: "Dry run: decide everything, write nothing (no promotion, tag, Release or publish)"
179
+ type: boolean
180
+ default: false
116
181
 
117
182
  # One release run at a time; a second one waits rather than racing the first for the same
118
183
  # candidate number. Never cancelled mid-run: a half-finished run may have pushed a tag
119
184
  # without publishing it.
120
185
  concurrency:
121
- group: release-auto
186
+ # A dry run (#474) gets a group of its own: GitHub cancels an older PENDING run in the same group,
187
+ # so a shared one could let a branch's dry run displace a real release run waiting on main.
188
+ group: release-auto${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') && format('-dry-{0}', github.ref_name) || '' }}
122
189
  cancel-in-progress: false
123
190
 
124
191
  permissions: {}
@@ -131,8 +198,38 @@ env:
131
198
  # next the newest candidate (vX.Y.Z-rc.N) — the fast channel
132
199
  # vX.Y.Z an exact version tag — frozen; moving it is a deliberate act, like re-copying
133
200
  # a template
201
+ # A ref the handbook does not carry (e.g. `stable` before its first final, or on a mirror)
202
+ # falls back to the newest final tag new enough for this template, else `next`, with a warning —
203
+ # it never fails the run (#480).
134
204
  HANDBOOK_REF: "stable"
135
205
  HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
206
+ # A TRANSIENT UPSTREAM ERROR NEVER TURNS MAIN RED (#464). This run fires on every landing, and a
207
+ # red run at main's head blocks every `colab ship` — so a GitHub / registry 5xx, a 429, a timeout
208
+ # or a dropped connection must not fail a step that a plain re-run would pass. Every step that
209
+ # talks to the network runs its call through `retry_transient` (each step `eval`s this block):
210
+ # the command is re-run with backoff while its output names a transient error, up to
211
+ # RETRY_ATTEMPTS times, and the last attempt's output and exit code are what the step sees. A
212
+ # persistent transient error still fails, with its message; anything else fails at once.
213
+ # Retrying is only safe because every retried call is idempotent — a read, or a write whose
214
+ # re-run after success is a no-op (`colab release cut/finalize/promote` read a head already done
215
+ # as a no-op; a Release or npm version that already exists is a skip). Keep that true if you add one.
216
+ RETRY_ATTEMPTS: "4" # EDIT: tries per call; backoff 5s, 10s, 20s between them.
217
+ RETRY_TRANSIENT: |
218
+ exec 3>&2
219
+ TRANSIENT_PATTERN='HTTP (5[0-9][0-9]|429)|returned error: (5[0-9][0-9]|429)|No server is currently available|Service Unavailable|Bad Gateway|Gateway Time-?out|Internal Server Error|secondary rate limit|rate limit exceeded|ETIMEDOUT|ECONNRESET|EAI_AGAIN|socket hang up|i/o timeout|TLS handshake timeout|connection reset|Could not resolve host|remote end hung up|early EOF|RPC failed|code E(5[0-9][0-9]|429)'
220
+ retry_transient() {
221
+ local attempt=1 max="${RETRY_ATTEMPTS:-4}" delay="${RETRY_DELAY:-5}" rc out err
222
+ out="$(mktemp)"; err="$(mktemp)"
223
+ while :; do
224
+ rc=0
225
+ "$@" > "$out" 2> "$err" || rc=$?
226
+ if [ "$rc" -eq 0 ] || [ "$attempt" -ge "$max" ] || ! cat "$err" "$out" | grep -Eiq "$TRANSIENT_PATTERN"; then
227
+ cat "$out"; cat "$err" >&2; rm -f "$out" "$err"; return "$rc"
228
+ fi
229
+ echo "::warning::$1: transient error (attempt $attempt/$max), retrying in ${delay}s — $(cat "$err" "$out" | grep -Eim1 "$TRANSIENT_PATTERN")" >&3
230
+ sleep "$delay"; attempt=$((attempt + 1)); delay=$((delay * 2))
231
+ done
232
+ }
136
233
 
137
234
  jobs:
138
235
  release:
@@ -142,7 +239,9 @@ jobs:
142
239
  # the whole run as `skipped` at that main sha, and `colab ship` reads any finished run that is
143
240
  # neither success nor cancelled as "not green". Re-run CI green on that sha and the skipped
144
241
  # Release (auto) row would still sit beside it, refusing every ship until main moves.
145
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
242
+ # EDIT: PRIVATE repo → your ci.yml's self-hosted trunk label, e.g. [self-hosted, linux]
243
+ # (RUNNERS, above). ubuntu-latest only on a public repo.
244
+ runs-on: ubuntu-latest
146
245
  permissions:
147
246
  contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
148
247
  issues: write # finalize opens / comments on / closes the "release: vX.Y.Z" tracking issue
@@ -155,18 +254,39 @@ jobs:
155
254
  npm-dir: ${{ steps.npm-target.outputs.dir }}
156
255
  npm-gate: ${{ steps.npm-target.outputs.gate }}
157
256
  npm-package: ${{ steps.npm-target.outputs.package }}
257
+ # What the deploy job below needs (#446) — empty unless this run tagged a deploy-tag-fast final.
258
+ deploy-tag: ${{ steps.cut.outputs.final }}
259
+ health-url: ${{ steps.cut.outputs.health-url }}
158
260
  env:
159
261
  GH_TOKEN: ${{ github.token }}
262
+ # #474: 'true' on a dry run — a dispatch on any ref other than main, or one with dry_run set.
263
+ # Never on workflow_run or schedule. Every write below is off when it is.
264
+ # EDIT: if your trunk is not `main`, name it here too (the same branch as `ref:` below).
265
+ DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') }}
160
266
  steps:
161
267
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
162
268
  with:
163
- ref: main
269
+ # A dry run checks out the ref it was dispatched on — the fix being proven; every other run, main.
270
+ ref: ${{ env.DRY_RUN == 'true' && github.sha || 'main' }}
164
271
  # Full history plus tags: versions, bumps and "previous final" are all read from
165
272
  # git, and the on-trunk check refuses a shallow checkout outright.
166
273
  fetch-depth: 0
167
274
  # Left on deliberately: `colab release cut` / `finalize` push their tag over the
168
- # checkout's origin. The token is this job's, scoped by `permissions:` above.
169
- persist-credentials: true
275
+ # checkout's origin. The token is this job's, scoped by `permissions:` above. Off on a dry
276
+ # run (#474): nothing is pushed, so nothing should be able to push.
277
+ persist-credentials: ${{ env.DRY_RUN != 'true' }}
278
+
279
+ # #474: the marker ci-cure reads to recognise a dry run — its name must stay byte-identical to
280
+ # DRY_RUN_STEP in the handbook's tools/lib/ci-cure.js. Skipped on every ordinary run.
281
+ - name: Dry run — nothing is tagged, released or published
282
+ if: env.DRY_RUN == 'true'
283
+ run: |
284
+ {
285
+ echo "#### Dry run (#474)"
286
+ echo
287
+ echo "Dispatched on \`$GITHUB_REF_NAME\` @ \`$GITHUB_SHA\`. Every decision below runs with \`--dry\`; steps marked \`[publish]\` are skipped. Nothing is promoted, tagged, released or published."
288
+ echo
289
+ } >> "$GITHUB_STEP_SUMMARY"
170
290
 
171
291
  # A red CI run on main is not a candidate. Gated here rather than by a job-level `if:` so
172
292
  # this run concludes success, never `skipped` (#435; the comment on the job above).
@@ -188,7 +308,27 @@ jobs:
188
308
  - name: Fetch the colab CLI
189
309
  run: |
190
310
  set -euo pipefail
191
- git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"
311
+ eval "$RETRY_TRANSIENT"
312
+ # A HANDBOOK_REF the handbook does not carry falls back instead of failing (#480): `stable`
313
+ # exists only once a final has been cut, and a fork or mirror may never have it. The
314
+ # fallback is the newest final vX.Y.Z tag at or above MIN_FINAL, else `next`, and it says
315
+ # so. MIN_FINAL is the first final carrying every CLI verb this template calls (`--auto`,
316
+ # #422–#425): an older final rejects them, and that is a red run too (#427). A ref that
317
+ # does exist is always used as written; a failed listing fails the step, never guesses.
318
+ MIN_FINAL="v1.12.0"
319
+ REFS="$(retry_transient git ls-remote --heads --tags "$HANDBOOK_REPO")"
320
+ if ! grep -Eq "[[:space:]]refs/(heads|tags)/${HANDBOOK_REF//./\\.}$" <<< "$REFS"; then
321
+ FALLBACK="next"
322
+ for t in $(sed -nE 's#^[0-9a-f]+[[:space:]]+refs/tags/(v[0-9]+\.[0-9]+\.[0-9]+)$#\1#p' <<< "$REFS" | sort -V); do
323
+ [ "$(printf '%s\n' "$MIN_FINAL" "$t" | sort -V | head -n 1)" = "$MIN_FINAL" ] && FALLBACK="$t"
324
+ done
325
+ echo "::warning::HANDBOOK_REF \"$HANDBOOK_REF\" is not a branch or tag of $HANDBOOK_REPO — using \"$FALLBACK\" (the newest final tag from $MIN_FINAL on, else next). Set HANDBOOK_REF to silence this."
326
+ echo "HANDBOOK_REF \`$HANDBOOK_REF\` does not exist upstream — fetched \`$FALLBACK\` instead (#480)." >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
327
+ HANDBOOK_REF="$FALLBACK"
328
+ fi
329
+ # A clone that died half-way leaves a directory a second clone refuses — start clean each try.
330
+ fetch_cli() { rm -rf "$RUNNER_TEMP/colab-handbook"; git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"; }
331
+ retry_transient fetch_cli
192
332
  echo "COLAB=$RUNNER_TEMP/colab-handbook/tools/colab" >> "$GITHUB_ENV"
193
333
  # The tags are annotated; git needs an identity to write one.
194
334
  git config user.name "github-actions[bot]"
@@ -206,9 +346,11 @@ jobs:
206
346
  CI_WORKFLOW: "CI"
207
347
  run: |
208
348
  set -uo pipefail
349
+ eval "$RETRY_TRANSIENT"
209
350
  OUT="$RUNNER_TEMP/promote.json"
210
351
  rc=0
211
- node "$COLAB" promote --auto --json > "$OUT" || rc=$?
352
+ DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
353
+ retry_transient node "$COLAB" promote --auto ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
212
354
  if ! jq -e 'has("promoted")' "$OUT" > /dev/null 2>&1; then
213
355
  echo "::warning::colab promote --auto gave no verdict (exit $rc; a HANDBOOK_REF older than #440?) — nothing was promoted"
214
356
  exit 0
@@ -219,10 +361,13 @@ jobs:
219
361
  jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
220
362
  echo
221
363
  } >> "$GITHUB_STEP_SUMMARY"
222
- if [ "$(jq -r '.promoted' "$OUT")" = "true" ]; then
364
+ if [ "${DRY_RUN:-false}" = "true" ]; then
365
+ # #474: a dry run promotes nothing and dispatches nothing, whatever the verdict says.
366
+ echo "Dry run — promote: $(jq -r 'if .promoted then "would promote" elif .noop then "no-op: \(.reason)" else "would refuse: \(.reason)" end' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
367
+ elif [ "$(jq -r '.promoted' "$OUT")" = "true" ]; then
223
368
  echo "promoted=true" >> "$GITHUB_OUTPUT"
224
369
  echo "Promoted to main @ $(jq -r '.sha' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
225
- if gh workflow run "$CI_WORKFLOW" --ref main; then
370
+ if retry_transient gh workflow run "$CI_WORKFLOW" --ref main; then
226
371
  echo "Dispatched $CI_WORKFLOW on main — its green run cuts the candidate." | tee -a "$GITHUB_STEP_SUMMARY"
227
372
  else
228
373
  echo "::warning::promoted, but could not dispatch $CI_WORKFLOW on main (does it declare workflow_dispatch:?) — run it by hand to cut the candidate"
@@ -242,12 +387,15 @@ jobs:
242
387
  if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
243
388
  run: |
244
389
  set -uo pipefail
390
+ eval "$RETRY_TRANSIENT"
245
391
  OUT="$RUNNER_TEMP/cut.json"
246
392
  rc=0
247
- node "$COLAB" release cut --auto --json > "$OUT" || rc=$?
393
+ DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
394
+ retry_transient node "$COLAB" release cut --auto ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
248
395
  # A verdict is JSON carrying `ok`; anything else is a run that never decided.
249
396
  if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
250
397
  echo "::error::colab release cut produced no verdict (exit $rc)"
398
+ echo "colab release cut produced no verdict (exit $rc) — the reason is in this step's log." >> "$GITHUB_STEP_SUMMARY"
251
399
  cat "$OUT"
252
400
  exit 1
253
401
  fi
@@ -257,16 +405,39 @@ jobs:
257
405
  jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
258
406
  echo
259
407
  } >> "$GITHUB_STEP_SUMMARY"
260
- if [ "$(jq -r '.created' "$OUT")" = "true" ]; then
408
+ if [ "${DRY_RUN:-false}" = "true" ]; then
409
+ # #474: a dry run never hands a tag to the publishing steps, whatever the verdict says.
410
+ echo "Dry run — would cut: $(jq -r '.tag // "nothing"' "$OUT") (created: $(jq -r '.created' "$OUT"))" | tee -a "$GITHUB_STEP_SUMMARY"
411
+ elif [ "$(jq -r '.created' "$OUT")" = "true" ]; then
261
412
  TAG="$(jq -r '.tag' "$OUT")"
262
413
  echo "tag=$TAG" >> "$GITHUB_OUTPUT"
263
414
  echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
415
+ # #446: on route deploy-tag-fast the cut IS the final, and the deploy job deploys it in
416
+ # this run (a tag pushed with GITHUB_TOKEN starts no `push: tags` workflow).
417
+ if [ "$(jq -r '.final // false' "$OUT")" = "true" ]; then
418
+ echo "final=$TAG" >> "$GITHUB_OUTPUT"
419
+ echo "health-url=$(jq -r '.deploy.healthUrl // ""' "$OUT")" >> "$GITHUB_OUTPUT"
420
+ fi
264
421
  elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
265
422
  echo "No-op: nothing owed, head already a candidate, inside a declared cadence window, or main's head is not a promotion." | tee -a "$GITHUB_STEP_SUMMARY"
266
423
  elif [ "$(jq -r '.ok' "$OUT")" = "true" ]; then
267
424
  echo "Verdict ok but nothing created." | tee -a "$GITHUB_STEP_SUMMARY"
268
425
  else
269
- echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | .condition] | join(", ")' "$OUT")"
426
+ # #467: a refusal no later run clears by itself (no first final, a malformed marker, a
427
+ # wrong manifest) is a STALL — an error annotation and a summary banner, still exit 0: a red
428
+ # release run at main's head would make trunk not-green and refuse the very ship that fixes it.
429
+ STANDING="$(jq -r '(.standing // []) | join(", ")' "$OUT")"
430
+ if [ -n "$STANDING" ]; then
431
+ echo "::error title=Release stalled::colab release cut refused on a condition that does not clear by itself: $(jq -r '. as $v | [$v.checks[]? | select(.ok | not) | select(.condition as $c | any(($v.standing // [])[]; . == $c)) | "\(.condition) — \(.detail)"] | join("; ")' "$OUT")"
432
+ {
433
+ echo "#### ⚠ Release stalled"
434
+ echo
435
+ echo "\`colab release cut --auto\` refused on **$STANDING** — the next run refuses the same way until a human acts (the ✗ rows above say what). The run stays green on purpose, so it never blocks the ship that fixes it."
436
+ echo
437
+ } >> "$GITHUB_STEP_SUMMARY"
438
+ else
439
+ echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | .condition] | join(", ")' "$OUT")"
440
+ fi
270
441
  fi
271
442
 
272
443
  - name: Finalize the newest clean candidate (colab release finalize --auto)
@@ -274,38 +445,53 @@ jobs:
274
445
  if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
275
446
  run: |
276
447
  set -uo pipefail
448
+ eval "$RETRY_TRANSIENT"
277
449
  OUT="$RUNNER_TEMP/finalize.json"
278
450
  rc=0
279
- node "$COLAB" release finalize --auto --json > "$OUT" || rc=$?
451
+ DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
452
+ retry_transient node "$COLAB" release finalize --auto ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
280
453
  if ! jq -e 'has("state")' "$OUT" > /dev/null 2>&1; then
281
454
  echo "::error::colab release finalize produced no verdict (exit $rc)"
455
+ echo "colab release finalize produced no verdict (exit $rc) — the reason is in this step's log." >> "$GITHUB_STEP_SUMMARY"
282
456
  cat "$OUT"
283
457
  exit 1
284
458
  fi
285
459
  STATE="$(jq -r '.state' "$OUT")"
460
+ # #468: why no final, and every other open candidate with its own reason — the checklist
461
+ # above it is only the picked candidate's, which alone reads as "only the newest counts".
462
+ WHY="$(jq -r '.why.line // empty' "$OUT")"
286
463
  {
287
464
  echo "### colab release finalize --auto — $STATE"
288
465
  echo
289
466
  jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
290
467
  echo
468
+ if [ -n "$WHY" ]; then echo "**Why no final:** $WHY"; echo; fi
469
+ if [ "$(jq -r '(.skipped // []) | length' "$OUT")" != "0" ]; then
470
+ echo "Other open candidates:"
471
+ jq -r '(.skipped // [])[:10][] | "- \(.tag): \(.state)\(if .detail then " — \(.detail)" else "" end)"' "$OUT"
472
+ jq -r '(.skipped // []) | if length > 10 then "- … \(length - 10) more" else empty end' "$OUT"
473
+ echo
474
+ fi
291
475
  } >> "$GITHUB_STEP_SUMMARY"
292
- if [ "$(jq -r '.tagged' "$OUT")" = "true" ]; then
476
+ if [ "${DRY_RUN:-false}" = "true" ]; then
477
+ echo "Dry run — finalize: $STATE (would tag: $(jq -r '.finalTag // "nothing"' "$OUT"))" | tee -a "$GITHUB_STEP_SUMMARY"
478
+ elif [ "$(jq -r '.tagged' "$OUT")" = "true" ]; then
293
479
  TAG="$(jq -r '.finalTag' "$OUT")"
294
480
  echo "tag=$TAG" >> "$GITHUB_OUTPUT"
295
481
  echo "Finalized $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
296
482
  else
297
483
  case "$STATE" in
298
- refused|needs-new-candidate|held) echo "::warning::colab release finalize: $STATE" ;;
299
- *) echo "Finalize: $STATE" ;;
484
+ refused|needs-new-candidate|held) echo "::warning::colab release finalize: $STATE${WHY:+ — $WHY}" ;;
485
+ *) echo "Finalize: $STATE${WHY:+ — $WHY}" ;;
300
486
  esac
301
487
  fi
302
488
 
303
489
  # Whether the npm job publishes what this run tagged — `colab release npm` reads the
304
490
  # release: block (one reading, the same as cut/finalize). A CLI older than #433 gives no
305
491
  # verdict; that is a warning and no npm publish, never a failed release.
306
- - name: Read the npm target (colab release npm)
492
+ - name: Read the npm target (colab release npm) [publish]
307
493
  id: npm-target
308
- if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
494
+ if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '')
309
495
  env:
310
496
  TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
311
497
  run: |
@@ -334,12 +520,13 @@ jobs:
334
520
 
335
521
  # Publishes every tag THIS run created. In this run, never via a tag-push workflow:
336
522
  # see "PUBLISHING HAPPENS IN THIS RUN" in the header.
337
- - name: Publish GitHub Release (same run)
338
- if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
523
+ - name: Publish GitHub Release (same run) [publish]
524
+ if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '')
339
525
  env:
340
526
  TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
341
527
  run: |
342
528
  set -euo pipefail
529
+ eval "$RETRY_TRANSIENT"
343
530
  for TAG in $TAGS; do
344
531
  if gh release view "$TAG" > /dev/null 2>&1; then
345
532
  echo "$TAG already has a Release — skipping"
@@ -358,7 +545,20 @@ jobs:
358
545
  *-*) KIND=(--prerelease --latest=false) ;;
359
546
  *) KIND=(--latest) ;;
360
547
  esac
361
- gh release create "$TAG" --verify-tag --title "$TAG" --notes-file "$NOTES" --generate-notes "${KIND[@]}"
548
+ # The view above is a check, not a lock: `colab release cut` publishes a candidate's
549
+ # pre-release itself, and the API can still answer 404 for it seconds later (#462 — a
550
+ # trunk went red on exactly that 422). So a create refused because the Release already
551
+ # exists is the skip case too, decided from the create's own answer. That also covers a
552
+ # create the API applied but answered 5xx for: the retry's 422 is that skip (#464).
553
+ ERR="$RUNNER_TEMP/create-$TAG.err"
554
+ if ! retry_transient gh release create "$TAG" --verify-tag --title "$TAG" --notes-file "$NOTES" --generate-notes "${KIND[@]}" 2> "$ERR"; then
555
+ cat "$ERR" >&2
556
+ if grep -qiE 'already[ _]exists' "$ERR"; then
557
+ echo "$TAG already has a Release (published while this step ran) — skipping"
558
+ continue
559
+ fi
560
+ exit 1
561
+ fi
362
562
  echo "Published $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
363
563
  done
364
564
 
@@ -404,10 +604,14 @@ jobs:
404
604
  - name: Refuse a private repository, and any npm token
405
605
  run: |
406
606
  set -uo pipefail
407
- # Visibility from the API, never assumed: unknown is refused like private.
408
- PRIVATE="$(gh api "repos/$REPO" --jq '.private' 2> /dev/null || echo unknown)"
607
+ eval "$RETRY_TRANSIENT"
608
+ # Visibility from the API, never assumed: unknown is refused like private. A transient
609
+ # error on this read is retried (#464) — one 5xx here once turned a trunk red.
610
+ ERR="$RUNNER_TEMP/visibility.err"
611
+ PRIVATE="$(retry_transient gh api "repos/$REPO" --jq '.private' 2> "$ERR")" || PRIVATE=unknown
409
612
  if [ "$PRIVATE" != "false" ]; then
410
- echo "::error::$REPO is private (or its visibility could not be read: $PRIVATE) — a private repository never publishes to public npm (#432). Remove release.npm, or install from git."
613
+ WHY="$(grep -v '^::warning::' "$ERR" 2> /dev/null | tail -n 1)"
614
+ echo "::error::$REPO is private (or its visibility could not be read: $PRIVATE${WHY:+ — $WHY}) — a private repository never publishes to public npm (#432). Remove release.npm, or install from git."
411
615
  exit 1
412
616
  fi
413
617
  if [ -n "${NODE_AUTH_TOKEN:-}${NPM_TOKEN:-}" ]; then
@@ -427,8 +631,9 @@ jobs:
427
631
  - name: npm new enough for trusted publishing (>= 11.5.1)
428
632
  run: |
429
633
  set -euo pipefail
634
+ eval "$RETRY_TRANSIENT"
430
635
  if ! node -e 'const [a,b,c]=process.argv[1].split(".").map(Number);process.exit(a>11||(a===11&&(b>5||(b===5&&c>=1)))?0:1)' "$(npm --version)"; then
431
- npm install --global npm@11
636
+ retry_transient npm install --global npm@11
432
637
  fi
433
638
  npm --version
434
639
 
@@ -437,13 +642,15 @@ jobs:
437
642
  - name: Publish each tag (npm publish --provenance)
438
643
  run: |
439
644
  set -euo pipefail
645
+ eval "$RETRY_TRANSIENT"
440
646
  for TAG in $TAGS; do
441
647
  VERSION="${TAG#v}"
442
648
  case "$VERSION" in
443
649
  *-*) DIST=next ;;
444
650
  *) DIST=latest ;;
445
651
  esac
446
- if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
652
+ # A 404 is "not published" and answers at once; a transient error is retried first (#464).
653
+ if retry_transient npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
447
654
  echo "$PACKAGE@$VERSION is already on npm — skipping" | tee -a "$GITHUB_STEP_SUMMARY"
448
655
  continue
449
656
  fi
@@ -451,7 +658,18 @@ jobs:
451
658
  git clean -fdxq
452
659
  (cd "$PKG_DIR" && npm pkg set "version=$VERSION")
453
660
  sh -c "$GATE"
454
- (cd "$PKG_DIR" && npm publish --tag "$DIST" --provenance --access public --ignore-scripts)
661
+ # The view above is a check, not a lock: a publish the registry applied but answered 5xx
662
+ # for, or one that landed between the view and here, is refused as a republish — the skip
663
+ # case again, decided from the publish's own answer (#464, the same shape as #462).
664
+ ERR="$RUNNER_TEMP/npm-publish-$VERSION.err"
665
+ if ! (cd "$PKG_DIR" && retry_transient npm publish --tag "$DIST" --provenance --access public --ignore-scripts) 2> "$ERR"; then
666
+ cat "$ERR" >&2
667
+ if grep -qiE 'EPUBLISHCONFLICT|cannot publish over (the )?previously published' "$ERR"; then
668
+ echo "$PACKAGE@$VERSION is already on npm (published while this step ran) — skipping" | tee -a "$GITHUB_STEP_SUMMARY"
669
+ continue
670
+ fi
671
+ exit 1
672
+ fi
455
673
  echo "Published $PACKAGE@$VERSION to npm (dist-tag $DIST)" | tee -a "$GITHUB_STEP_SUMMARY"
456
674
  done
457
675
 
@@ -461,7 +679,8 @@ jobs:
461
679
  name: Record the npm outcome on the Release
462
680
  needs: [release, npm]
463
681
  if: always() && needs.release.outputs.npm == 'true'
464
- runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
682
+ # EDIT: the same label as `release` above — PRIVATE repo → self-hosted (RUNNERS, above).
683
+ runs-on: ubuntu-latest
465
684
  permissions:
466
685
  contents: write # edit the Release notes
467
686
  env:
@@ -475,10 +694,17 @@ jobs:
475
694
  - name: Record the npm outcome
476
695
  run: |
477
696
  set -euo pipefail
697
+ eval "$RETRY_TRANSIENT"
478
698
  for TAG in $TAGS; do
479
- BODY="$(gh release view "$TAG" --repo "$REPO" --json body --jq '.body' 2> /dev/null)" || {
480
- echo "$TAG has no Release — nothing to record on"
481
- continue
699
+ ERR="$RUNNER_TEMP/record-$TAG.err"
700
+ BODY="$(retry_transient gh release view "$TAG" --repo "$REPO" --json body --jq '.body' 2> "$ERR")" || {
701
+ # Only a Release that is not there is nothing to record on; a read that kept failing is a failure.
702
+ if grep -qiE 'release not found|HTTP 404|Not Found' "$ERR"; then
703
+ echo "$TAG has no Release — nothing to record on"
704
+ continue
705
+ fi
706
+ cat "$ERR" >&2
707
+ exit 1
482
708
  }
483
709
  VERSION="${TAG#v}"
484
710
  case "$VERSION" in *-*) DIST=next ;; *) DIST=latest ;; esac
@@ -490,6 +716,89 @@ jobs:
490
716
  NOTES="$RUNNER_TEMP/notes-$TAG.md"
491
717
  printf '%s\n' "$BODY" | sed '/^<!-- colab:npm -->$/,/^<!-- \/colab:npm -->$/d' > "$NOTES"
492
718
  printf '\n<!-- colab:npm -->\n%s\n<!-- /colab:npm -->\n' "$LINE" >> "$NOTES"
493
- gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
719
+ # Idempotent: the block between the colab:npm markers is replaced, never appended twice.
720
+ retry_transient gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
494
721
  echo "$TAG: $LINE" | tee -a "$GITHUB_STEP_SUMMARY"
495
722
  done
723
+
724
+ # ---------------------------------------------------------------------------------------------
725
+ # deploy (#446) — route deploy-tag-fast only: deploys the final the release job just tagged, in
726
+ # this same run, then verifies it. Skipped on every other route (deploy-tag stays empty).
727
+ #
728
+ # Same run, never a tag-triggered deploy workflow: a tag pushed with GITHUB_TOKEN starts no
729
+ # `push: tags` run, so a separate deploy-on-tag workflow would never fire for this final.
730
+ #
731
+ # The health check is the handbook's half of the "health-gated deploy with automatic rollback"
732
+ # the route requires: it fails this job when release.health-url does not report the version in
733
+ # time. The ROLLBACK is your deploy's own (release.rollback: auto is your statement that it has
734
+ # one) — this job does not roll anything back. A failed deploy leaves the tag standing and this
735
+ # run red; fix forward, or re-run the failed job to deploy the same tag again.
736
+ deploy:
737
+ name: Deploy the final (deploy-tag-fast)
738
+ needs: release
739
+ if: needs.release.outputs.deploy-tag != ''
740
+ runs-on: ubuntu-latest # EDIT: the runner your deploy needs — self-hosted on a PRIVATE repo (RUNNERS, above).
741
+ environment: production # EDIT: the GitHub environment holding your deploy secrets, or remove.
742
+ permissions:
743
+ contents: read # check out the tag
744
+ env:
745
+ TAG: ${{ needs.release.outputs.deploy-tag }}
746
+ HEALTH_URL: ${{ needs.release.outputs.health-url }}
747
+ HEALTH_TIMEOUT_SECONDS: "600" # EDIT: how long the new version may take to report itself.
748
+ steps:
749
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
750
+ with:
751
+ ref: refs/tags/${{ needs.release.outputs.deploy-tag }}
752
+ persist-credentials: false # nothing here pushes
753
+
754
+ # EDIT: replace this step's body with your deploy of "$TAG" (an image push + rollout, an
755
+ # SSH script, a platform CLI). It must roll back by itself when the new version fails its
756
+ # health check — that is what release.rollback: auto declares. Until edited it fails, so a
757
+ # final is never reported deployed when nothing deployed it.
758
+ - name: Deploy the final (EDIT)
759
+ run: |
760
+ set -euo pipefail
761
+ echo "::error::the deploy step of release-auto.yml was never edited — $TAG is tagged and published but NOT deployed. Replace this step with your deploy (templates/release-auto.yml, DEPLOYING IN THIS RUN)."
762
+ exit 1
763
+
764
+ - name: Verify the health endpoint reports the final
765
+ run: |
766
+ set -uo pipefail
767
+ VERSION="${TAG#v}"
768
+ # Boundary-aware, the same rule as deploy-container-run.mjs `reportsVersion` (#459): the
769
+ # version (optionally `v`-prefixed) must not touch a digit or `.` before it, nor a digit or
770
+ # `.`+digit after it — so 1.2.1 never matches 1.2.10, 11.2.1 or 1.2.1.4. A substring
771
+ # `case` match accepted all three. grep is line-based; a newline is neither, so it agrees.
772
+ PATTERN="(^|[^0-9.])v?${VERSION//./\\.}([^0-9.]|\\.([^0-9]|\$)|\$)"
773
+ DEADLINE=$(( $(date +%s) + HEALTH_TIMEOUT_SECONDS ))
774
+ while :; do
775
+ BODY="$(curl -fsS --max-time 10 "$HEALTH_URL" 2> /dev/null || true)"
776
+ if printf '%s\n' "$BODY" | grep -Eq -- "$PATTERN"; then
777
+ echo "$HEALTH_URL reports $VERSION — $TAG is live" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0
778
+ fi
779
+ if [ "$(date +%s)" -ge "$DEADLINE" ]; then
780
+ echo "::error::$HEALTH_URL did not report $VERSION within ${HEALTH_TIMEOUT_SECONDS}s — the deploy's own rollback should have restored the previous version; $TAG stays tagged"
781
+ exit 1
782
+ fi
783
+ sleep 10
784
+ done
785
+
786
+ # ON deploy-container.yml (#452): replace the whole `deploy` job above with this one. It calls the
787
+ # same workflow a human-pushed final runs (`push: tags`), so the fast route and route deploy-tag
788
+ # share ONE deploy path — build once, run exactly the tag, verify release.health-url, roll back.
789
+ # Commented because a live `uses:` of a file your repo does not have breaks this workflow.
790
+ # A reusable workflow's permissions are capped by the calling job's, hence the three below.
791
+ #
792
+ # deploy:
793
+ # name: Deploy the final (deploy-tag-fast)
794
+ # needs: release
795
+ # if: needs.release.outputs.deploy-tag != ''
796
+ # permissions:
797
+ # contents: read
798
+ # packages: write
799
+ # issues: write
800
+ # uses: ./.github/workflows/deploy-container.yml
801
+ # with:
802
+ # tag: ${{ needs.release.outputs.deploy-tag }}
803
+ # health-url: ${{ needs.release.outputs.health-url }}
804
+ # secrets: inherit