@futurelastic/colab-handbook 1.21.0-rc.6 → 1.21.0-rc.8

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/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.21.0-rc.6"
36
+ "version": "1.21.0-rc.8"
37
37
  }
@@ -110,7 +110,7 @@ check that reads one of these files is that tool's behaviour, documented with th
110
110
  | `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. **Still a copy** (#724 kept it one: it runs nightly and on candidates, never per merge, so it is not what drifted, and its plan gate is per-repo). Its toolchain resolution follows the same precedence as the reusable light lane's, and the `secrets` job's gitleaks install and `GITLEAKS_VERSION` follow its `gitleaks` job — keep them in step. `TRUNK` is an edit point. |
111
111
  | `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | A **caller** of `ci-light.yml` (#724): byte-compile, ruff and mypy in `quick`, pytest in `full`, each only if installed. The call resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: `toolchain: python,node` in the same call — see the template header. Opt-in `Migration round-trip` job, as in `ci-node.yml`. |
112
112
  | `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
113
- | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
113
+ | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547). A first job, `decide`, skips the heavy job on a run with nothing to do: a red CI run, a CI run at a sha that already carries its tag, or an hourly run with nothing to retry (#735). It uses a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
114
114
  | `forgejo-release-auto.yml` | `.forgejo/workflows/release-auto.yml` | A repo hosted on **Forgejo** (or Gitea) whose §6 release route cuts candidates, with the forge named in the machine config's `forges` (#678) | The Forgejo dialect of `release-auto.yml` (#681). It has no `workflow_run`: the job you append to your CI (in its header) dispatches it when CI ends green, with `source=ci-completed` and the sha it tested. It waits for CI at that sha (`colab ci-wait`), then runs `colab release cut --auto --sha`, which tags the candidate and publishes its pre-release through the forge's API. No `permissions:` blocks, full-URL `uses:`, the runner label from the `RELEASE_RUNNER` variable, verdicts printed to the log (Forgejo drops the step summary), no `jq`. A refusal stays green. No verdict is a red run. **No finalize step**: on a forge a final is a human's `release finalize` under the human bar, which also publishes the final's release, so no tag-push workflow is needed. Keep its `name:` equal to the file's base name, because the CLI drops its own statuses by that name. |
115
115
  | `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. |
116
116
  | `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. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.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). |
@@ -200,6 +200,31 @@ once, for every caller; `ci-node.yml`, `ci-python.yml` and `ci-laravel.yml` are
200
200
  - **The quick/full split is two jobs**: `quick` (descriptor check, lint, types, unit — the `quick` class)
201
201
  and `full` (the light suite, the build — the `full` class); both run on every push the gate does not skip,
202
202
  and both take the `trunk` class on a trunk ref under `runs-on: classes`.
203
+ - **On a non-trunk ref, full starts only after quick passed** (#734). Those are the refs `concurrency`
204
+ cancels, and a run cancelled by the next push used to have every lane running already: late cancels
205
+ were 8.5% of a self-hosted fleet's runner-minutes over 14 days. A trunk run is unchanged — never
206
+ cancelled, never delayed, full beside quick. `needs:` cannot be conditional, so the call holds the full
207
+ command as two jobs of one name (`full` on trunk, `full-staged` elsewhere); exactly one runs, a required
208
+ check by name is met by it, and the gate does not count the skipped twin as a skip (#511).
209
+ A red quick on a branch therefore hides that push's full failures until quick is fixed — the price of
210
+ not paying for a full run whose verdict is already red.
211
+ - **Not calling it yet?** A hand-written CI with heavy jobs (full tests, browser/e2e, desktop builds) should
212
+ stage them the same way: on a non-trunk ref, `needs:` the quick job and require
213
+ `needs.<quick>.result == 'success'`; on a trunk ref, keep them beside it. The pair, as the call writes it:
214
+ ```yaml
215
+ e2e: # trunk twin — unchanged
216
+ needs: dedupe
217
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && contains(fromJSON('["main","dev"]'), github.ref_name) }}
218
+ e2e-staged: # every other ref — the ones concurrency cancels
219
+ name: <the same name as e2e>
220
+ needs: [dedupe, quick]
221
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && needs.quick.result == 'success' && !contains(fromJSON('["main","dev"]'), github.ref_name) }}
222
+ ```
223
+ Give both twins one `name:` and identical steps. If your copy carries the dedupe guard, its #511 skip
224
+ rule must also pass over a skipped job whose name a successful job of the same run carries (the call's
225
+ guard does — copy that `jq`), or no branch run can be cited at the landing again.
226
+ - **Mid-session backup pushes start no run at all** when they go to `refs/backup/<branch>` instead of the
227
+ branch (CONVENTIONS.md §7, *One verdict per tree*, rule 5).
203
228
  - **The package caches moved too**: npm, pip and Composer, each on only on a GitHub-hosted runner and with
204
229
  its lockfile present (#571), now in the call. Laravel's PHP extensions are the `php-extensions` input.
205
230
  - A workflow still carrying its own copy of the gate is reported as drift — a suggestion until a handbook
@@ -2,7 +2,8 @@
2
2
  # with `colab template ci-call --dest .github/workflows/ci.yml`: it writes this repo's trunk refs and pins the call to the handbook
3
3
  # release it stamps the copy with. Like templates/ci-<stack>.yml (callers too since #724, each with one
4
4
  # stack's `with:` filled in — this one is the generic caller, for a hybrid), nothing below the `uses:` line is
5
- # yours to maintain — the dedupe gate, the secret scan, the quick/full split and the job-class
5
+ # yours to maintain — the dedupe gate, the secret scan, the quick/full split (full staged behind quick on
6
+ # a non-trunk ref, #734) and the job-class
6
7
  # `runs-on` live once, in .github/workflows/ci-light.yml of the handbook, and a release moves them.
7
8
  #
8
9
  # EDIT POINTS are marked `# EDIT:` — the `with:` block is the only real one.
@@ -189,9 +189,26 @@
189
189
  # Every other hourly run checks those and stops: no cut, no promotion, no finalize, so a held head is
190
190
  # not tagged sooner than the daily run would tag it, and a standing refusal is not re-announced every
191
191
  # hour. Nothing is stored between runs; the facts are re-read each time. EDIT: the cron string inside
192
- # RETRY_RUN (release job env) must stay byte-identical to the hourly `cron:` line, or no run is
192
+ # RETRY_RUN (the workflow `env:`) must stay byte-identical to the hourly `cron:` line, or no run is
193
193
  # recognised as a retry run — and the hourly run would then promote and finalize every hour.
194
194
  #
195
+ # A RUN WITH NOTHING TO DO ENDS IN SECONDS (#735). Most runs find nothing to do — the hourly run with
196
+ # nothing to retry, a CI re-run at a commit that already carries its tag, a red CI run — and each one
197
+ # used to take a runner and pay the full setup (full-history checkout, CLI fetch) before saying so. So
198
+ # the first job, `decide`, rules on the cases it can prove with a one-commit checkout and a tag list,
199
+ # and `release` (and with it `npm`, `npm-record`, `deploy` and your downloads jobs, which all need it)
200
+ # runs only when `decide` says there is work:
201
+ # workflow_run, CI not green no work — nothing is cut at a red sha
202
+ # workflow_run, the sha already carries a no work — the cut there is a no-op (#443), and a run
203
+ # release tag (vX.Y.Z or vX.Y.Z-rc.N) fired by CI does nothing but the cut and what it tags
204
+ # the hourly run the #547 retry step's verdict (it lives in `decide`)
205
+ # the daily run, a dispatch always work — promotion, finalize and the npm and
206
+ # downloads sweeps are the CLI's to rule on, and a dry
207
+ # run proves a fix only by running the whole job (#474)
208
+ # `decide` is a filter, never a second decider: it skips only where `release` is provably a no-op, and
209
+ # says "work" whenever it cannot read what it needs. It has no job-level `if:` and always concludes
210
+ # success, so a run that skips every other job still concludes success at main's sha (#435).
211
+ #
195
212
  # A REFUSAL IS NOT A FAILURE. `colab release cut --auto` refusing (nothing owed, a check
196
213
  # failed) is the ordinary output of most runs; it is printed to the run summary as a
197
214
  # warning and the job stays green, so a refusal never paints main red for `colab ship`.
@@ -221,7 +238,7 @@
221
238
  # owner's billing fails GitHub refuses a hosted job before it starts: main goes red, every landing
222
239
  # is refused until a human steps in — measured twice in a row on one adopting repo, where this was
223
240
  # the only workflow on main still on hosted runners. So:
224
- # private / internal repo `release` and `npm-record` run on the trunk class, `[self-hosted,
241
+ # private / internal repo `decide`, `release` and `npm-record` run on the trunk class, `[self-hosted,
225
242
  # trunk]` — the class your ci.yml's trunk jobs use (CONVENTIONS.md §7,
226
243
  # "Runner classes"); `deploy`, if you enable it, on its own restricted
227
244
  # deploy label. The runner needs git, node, gh and jq on its PATH
@@ -250,7 +267,7 @@ on:
250
267
  # hour is when scheduled runs queue longest.
251
268
  - cron: "17 3 * * *"
252
269
  # #547: the hourly RETRY run — cut only, only when the CLI moved or a run was displaced (header,
253
- # "A REFUSAL THE HANDBOOK FIXES"). Keep it byte-identical to the string in RETRY_RUN (release job env).
270
+ # "A REFUSAL THE HANDBOOK FIXES"). Keep it byte-identical to the string in RETRY_RUN (workflow `env:`).
254
271
  - cron: "47 * * * *"
255
272
  workflow_dispatch:
256
273
  # #474: a DRY RUN for a fix branch — see "DRY RUN ON A FIX BRANCH" in the header. A dispatch on
@@ -285,6 +302,9 @@ env:
285
302
  # it never fails the run (#480).
286
303
  HANDBOOK_REF: "stable"
287
304
  HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
305
+ # #547: 'true' on the hourly retry run, read by both jobs (#735). EDIT: the cron string here is
306
+ # byte-identical to the hourly `cron:` under `on.schedule`.
307
+ RETRY_RUN: ${{ github.event_name == 'schedule' && github.event.schedule == '47 * * * *' }}
288
308
  # A TRANSIENT UPSTREAM ERROR NEVER TURNS MAIN RED (#464). This run fires on every landing, and a
289
309
  # red run at main's head blocks every `colab ship` — so a GitHub / registry 5xx, a 429, a timeout
290
310
  # or a dropped connection must not fail a step that a plain re-run would pass. Every step that
@@ -354,13 +374,130 @@ env:
354
374
  }
355
375
 
356
376
  jobs:
377
+ # ---------------------------------------------------------------------------------------------
378
+ # decide (#735) — whether this run has any work, ruled on a one-commit checkout before any job that
379
+ # fetches history or the CLI starts. See "A RUN WITH NOTHING TO DO ENDS IN SECONDS" in the header.
380
+ decide:
381
+ name: Decide whether there is work
382
+ # No job-level `if:` and no `needs:` here, ever (#435): this job always runs and concludes success,
383
+ # which is what keeps the run from concluding `skipped` when it skips every other job. GitHub
384
+ # records a run whose every job a job-level `if:` skipped as `skipped` at that main sha, and
385
+ # `colab ship` reads any finished run that is neither success nor cancelled as "not green".
386
+ # EDIT: PRIVATE repo → the trunk class, [self-hosted, trunk] — the same label as `release` below
387
+ # (RUNNERS, above). ubuntu-latest only on a public repo.
388
+ runs-on: ubuntu-latest
389
+ permissions:
390
+ contents: read # list the tags (git ls-remote) over the checkout's origin
391
+ actions: read # the #547 retry reads this workflow's runs at main's head
392
+ outputs:
393
+ work: ${{ steps.work.outputs.work }}
394
+ retry: ${{ steps.retry.outputs.retry }}
395
+ env:
396
+ GH_TOKEN: ${{ github.token }}
397
+ # EDIT: how recent a move of the CLI still earns a retry (#547). Two hourly runs plus slack, so one
398
+ # scheduled run GitHub drops under load does not lose the retry; a second retry is a no-op.
399
+ RETRY_WINDOW_MINUTES: "130"
400
+ steps:
401
+ # One commit, no tags, no blobs outside .github: only what `git rev-parse HEAD` and `git ls-remote
402
+ # origin` need. EDIT: if your trunk is not `main`, name it here too (the same branch as below).
403
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
404
+ with:
405
+ ref: main
406
+ fetch-depth: 1
407
+ sparse-checkout: .github
408
+ # Left on: `git ls-remote origin` reads the tags with this job's read-only token.
409
+ persist-credentials: true
410
+
411
+ # #547: on the hourly retry run only — decide whether a cut is worth re-trying (header, "A REFUSAL
412
+ # THE HANDBOOK FIXES"). Ends green either way; retry=true is the hourly run's only work. A dry run
413
+ # never runs it (tools/lib/ci-cure.js DRY_RUN_CONDITIONAL_STEPS names it).
414
+ - name: Retry a refused cut once the CLI moved (#547)
415
+ id: retry
416
+ if: env.RETRY_RUN == 'true'
417
+ run: |
418
+ set -uo pipefail
419
+ eval "$RETRY_TRANSIENT"
420
+ decide() { echo "retry=$1" >> "$GITHUB_OUTPUT"; echo "Retry run (#547): $2" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0; }
421
+ HEAD="$(git rev-parse HEAD)"
422
+ # #735: this checkout carries no tags, so they are read from origin. A list that cannot be read
423
+ # rules nothing out — the checks below decide.
424
+ TAGGED=""
425
+ if REFS="$(retry_transient git ls-remote --tags origin)"; then
426
+ TAGGED="$(awk -v h="$HEAD" '$1 == h && $2 ~ /^refs\/tags\/v/ { t = substr($2, 11); if (substr(t, length(t) - 2) == "^{}") t = substr(t, 1, length(t) - 3); print t; exit }' <<< "$REFS")"
427
+ fi
428
+ [ -z "$TAGGED" ] || decide false "main's head ${HEAD:0:7} already carries $TAGGED — nothing to retry."
429
+ # When the CLI reached HANDBOOK_REF: a channel moves onto a release tag's commit, so that
430
+ # tag's date is the move; a plain branch or an untagged commit falls back to the commit date.
431
+ # #735: the ref is fetched here with no blobs and no working tree — only its commit and the tags
432
+ # at it are read. A ref that cannot be fetched (one the handbook does not carry, #480) cannot
433
+ # rule a move out: the release job fetches the CLI, with its fallback, and re-tries the cut.
434
+ CLI_DIR="$RUNNER_TEMP/colab-handbook-ref"
435
+ fetch_ref() { rm -rf "$CLI_DIR"; git clone --quiet --depth 1 --filter=blob:none --no-checkout --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$CLI_DIR"; }
436
+ retry_transient fetch_ref > /dev/null \
437
+ || decide true "could not fetch HANDBOOK_REF \"$HANDBOOK_REF\", so a move of the colab CLI cannot be ruled out and main's head ${HEAD:0:7} has no tag — re-trying the cut."
438
+ CLI_SHA="$(git -C "$CLI_DIR" rev-parse --short HEAD 2> /dev/null || echo unknown)"
439
+ MOVED="$(git -C "$CLI_DIR" for-each-ref --points-at HEAD --format='%(taggerdate:unix)' refs/tags 2> /dev/null | grep -E '^[0-9]+$' | sort -n | tail -n 1)"
440
+ [ -n "$MOVED" ] || MOVED="$(git -C "$CLI_DIR" log -1 --format=%ct HEAD 2> /dev/null || true)"
441
+ AGE=""; [ -n "$MOVED" ] && AGE=$(( $(date +%s) - MOVED ))
442
+ if [ -n "$AGE" ] && [ "$AGE" -le $(( ${RETRY_WINDOW_MINUTES:-130} * 60 )) ]; then
443
+ decide true "the colab CLI ($CLI_SHA) reached HANDBOOK_REF $(( AGE / 60 )) min ago and main's head ${HEAD:0:7} has no tag — re-trying the cut with it."
444
+ fi
445
+ # A run this one displaced: the newest OTHER run of this workflow at main's head, cancelled.
446
+ # An unreadable list re-tries rather than guessing — a cut with nothing owed is a no-op.
447
+ RUNS="$(retry_transient gh run list --workflow "$GITHUB_WORKFLOW" --commit "$HEAD" --limit 20 --json databaseId,conclusion,createdAt)" \
448
+ || decide true "could not list this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut."
449
+ LAST="$(jq -r --arg me "${GITHUB_RUN_ID:-0}" '[.[] | select((.databaseId | tostring) != $me)] | sort_by(.createdAt) | last | .conclusion // ""' <<< "$RUNS" 2> /dev/null || echo unreadable)"
450
+ case "$LAST" in
451
+ cancelled) decide true "the last run at main's head ${HEAD:0:7} was cancelled (displaced from the shared concurrency group) — doing its cut." ;;
452
+ unreadable) decide true "could not read this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut." ;;
453
+ esac
454
+ decide false "the colab CLI ($CLI_SHA) has not moved in the last ${RETRY_WINDOW_MINUTES:-130} min and no run at ${HEAD:0:7} was displaced — nothing to retry; the daily run cuts as usual."
455
+
456
+ # #735: the verdict the other jobs read — work=true whenever this job cannot prove the run is a
457
+ # no-op (header, "A RUN WITH NOTHING TO DO ENDS IN SECONDS"). Ends green either way.
458
+ - name: Decide whether this run has work
459
+ id: work
460
+ env:
461
+ EVENT: ${{ github.event_name }}
462
+ CONCLUSION: ${{ github.event.workflow_run.conclusion }}
463
+ RUN_SHA: ${{ github.event.workflow_run.head_sha }}
464
+ RETRY: ${{ steps.retry.outputs.retry }}
465
+ run: |
466
+ set -uo pipefail
467
+ eval "$RETRY_TRANSIENT"
468
+ decide() { echo "work=$1" >> "$GITHUB_OUTPUT"; echo "Work (#735): $2" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0; }
469
+ case "${EVENT:-}" in
470
+ workflow_dispatch)
471
+ decide true "a dispatch runs the whole release job — a dry run proves a fix only by running it (#474)." ;;
472
+ schedule)
473
+ if [ "${RETRY_RUN:-false}" != "true" ]; then
474
+ decide true "the daily run — promotion, finalize and the npm and downloads sweeps are the colab CLI's to rule on."
475
+ elif [ "${RETRY:-}" = "true" ]; then
476
+ decide true "the hourly run re-tries the cut (the retry step above says why)."
477
+ else
478
+ decide false "the hourly run has nothing to retry, and it never promotes, finalizes or sweeps — the release job does not start."
479
+ fi ;;
480
+ workflow_run)
481
+ [ "${CONCLUSION:-}" = "success" ] \
482
+ || decide false "CI concluded \`${CONCLUSION:-unknown}\` at ${RUN_SHA:-an unnamed sha} — nothing to cut; the release job does not start."
483
+ [ -n "${RUN_SHA:-}" ] || decide true "the CI run names no sha — the release job reads main itself."
484
+ REFS="$(retry_transient git ls-remote --tags origin)" \
485
+ || decide true "could not list the tags, so a release tag at ${RUN_SHA:0:7} cannot be ruled in — the release job decides."
486
+ AT="$(awk -v s="$RUN_SHA" '$1 == s { t = substr($2, 11); if (substr(t, length(t) - 2) == "^{}") t = substr(t, 1, length(t) - 3); if (substr($2, 1, 10) == "refs/tags/" && t ~ /^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[1-9][0-9]*)?$/) { print t; exit } }' <<< "$REFS")"
487
+ [ -z "$AT" ] \
488
+ || decide false "${RUN_SHA:0:7} already carries $AT — a cut there is a no-op (#443), and a run fired by CI does nothing else; the release job does not start."
489
+ decide true "${RUN_SHA:0:7} carries no release tag — the release job decides the cut." ;;
490
+ *)
491
+ decide true "event \`${EVENT:-unknown}\` — the release job decides." ;;
492
+ esac
493
+
357
494
  release:
358
495
  name: Cut, finalize, publish
359
- # No job-level `if:` here, on purpose (#435): a red CI run is gated in the first step below,
360
- # so this run concludes success. A job-level `if:` would skip every job, GitHub would record
361
- # the whole run as `skipped` at that main sha, and `colab ship` reads any finished run that is
362
- # neither success nor cancelled as "not green". Re-run CI green on that sha and the skipped
363
- # Release (auto) row would still sit beside it, refusing every ship until main moves.
496
+ # #735: only when `decide` found work. This job-level `if:` cannot make the run conclude `skipped`
497
+ # (#435): `decide` always runs and concludes success, so a run that skips this job still concludes
498
+ # success at main's sha. A red CI run is gated in a step below as well, as before #735.
499
+ needs: decide
500
+ if: needs.decide.outputs.work == 'true'
364
501
  # EDIT: PRIVATE repo → the trunk class, [self-hosted, trunk] — a class, never a host
365
502
  # (RUNNERS, above). ubuntu-latest only on a public repo.
366
503
  runs-on: ubuntu-latest
@@ -390,12 +527,6 @@ jobs:
390
527
  # Never on workflow_run or schedule. Every write below is off when it is.
391
528
  # EDIT: if your trunk is not `main`, name it here too (the same branch as `ref:` below).
392
529
  DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') }}
393
- # #547: 'true' on the hourly retry run. EDIT: the cron string here is byte-identical to the hourly
394
- # `cron:` under `on.schedule`.
395
- RETRY_RUN: ${{ github.event_name == 'schedule' && github.event.schedule == '47 * * * *' }}
396
- # EDIT: how recent a move of the CLI still earns a retry. Two hourly runs plus slack, so one
397
- # scheduled run GitHub drops under load does not lose the retry; a second retry is a no-op.
398
- RETRY_WINDOW_MINUTES: "130"
399
530
  steps:
400
531
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
401
532
  with:
@@ -421,8 +552,8 @@ jobs:
421
552
  echo
422
553
  } >> "$GITHUB_STEP_SUMMARY"
423
554
 
424
- # A red CI run on main is not a candidate. Gated here rather than by a job-level `if:` so
425
- # this run concludes success, never `skipped` (#435; the comment on the job above).
555
+ # A red CI run on main is not a candidate. The decide job already skips the release job on one
556
+ # (#735); this step keeps that true on its own, so the cut never reads a red sha whatever runs it.
426
557
  - name: Gate on the triggering CI run
427
558
  id: gate
428
559
  env:
@@ -467,39 +598,6 @@ jobs:
467
598
  git config user.name "github-actions[bot]"
468
599
  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
469
600
 
470
- # #547: on the hourly retry run only — decide whether a cut is worth re-trying (header, "A REFUSAL
471
- # THE HANDBOOK FIXES"). Ends green either way; retry=true lets the cut step below run.
472
- - name: Retry a refused cut once the CLI moved (#547)
473
- id: retry
474
- if: env.RETRY_RUN == 'true'
475
- run: |
476
- set -uo pipefail
477
- eval "$RETRY_TRANSIENT"
478
- decide() { echo "retry=$1" >> "$GITHUB_OUTPUT"; echo "Retry run (#547): $2" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0; }
479
- HEAD="$(git rev-parse HEAD)"
480
- TAGGED="$(git tag --points-at "$HEAD" --list 'v*' | head -n 1)"
481
- [ -z "$TAGGED" ] || decide false "main's head ${HEAD:0:7} already carries $TAGGED — nothing to retry."
482
- # When the CLI reached HANDBOOK_REF: a channel moves onto a release tag's commit, so that
483
- # tag's date is the move; a plain branch or an untagged commit falls back to the commit date.
484
- CLI_DIR="${COLAB%/tools/colab}"
485
- CLI_SHA="$(git -C "$CLI_DIR" rev-parse --short HEAD 2> /dev/null || echo unknown)"
486
- MOVED="$(git -C "$CLI_DIR" for-each-ref --points-at HEAD --format='%(taggerdate:unix)' refs/tags 2> /dev/null | grep -E '^[0-9]+$' | sort -n | tail -n 1)"
487
- [ -n "$MOVED" ] || MOVED="$(git -C "$CLI_DIR" log -1 --format=%ct HEAD 2> /dev/null || true)"
488
- AGE=""; [ -n "$MOVED" ] && AGE=$(( $(date +%s) - MOVED ))
489
- if [ -n "$AGE" ] && [ "$AGE" -le $(( ${RETRY_WINDOW_MINUTES:-130} * 60 )) ]; then
490
- decide true "the colab CLI ($CLI_SHA) reached HANDBOOK_REF $(( AGE / 60 )) min ago and main's head ${HEAD:0:7} has no tag — re-trying the cut with it."
491
- fi
492
- # A run this one displaced: the newest OTHER run of this workflow at main's head, cancelled.
493
- # An unreadable list re-tries rather than guessing — a cut with nothing owed is a no-op.
494
- RUNS="$(retry_transient gh run list --workflow "$GITHUB_WORKFLOW" --commit "$HEAD" --limit 20 --json databaseId,conclusion,createdAt)" \
495
- || decide true "could not list this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut."
496
- LAST="$(jq -r --arg me "${GITHUB_RUN_ID:-0}" '[.[] | select((.databaseId | tostring) != $me)] | sort_by(.createdAt) | last | .conclusion // ""' <<< "$RUNS" 2> /dev/null || echo unreadable)"
497
- case "$LAST" in
498
- cancelled) decide true "the last run at main's head ${HEAD:0:7} was cancelled (displaced from the shared concurrency group) — doing its cut." ;;
499
- unreadable) decide true "could not read this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut." ;;
500
- esac
501
- decide false "the colab CLI ($CLI_SHA) has not moved in the last ${RETRY_WINDOW_MINUTES:-130} min and no run at ${HEAD:0:7} was displaced — nothing to retry; the daily run cuts as usual."
502
-
503
601
  # #440: where project.yml grants `promotion: main-loop` on `deploy: tag`, promote a green dev
504
602
  # into main, then dispatch CI there — its green run fires this workflow again to cut the
505
603
  # candidate. Everywhere else the CLI answers a no-op. A refusal (dev CI not green, a push
@@ -557,7 +655,7 @@ jobs:
557
655
  # (a release.guard-run reads the working tree) and restored afterwards.
558
656
  - name: Cut a candidate (colab release cut --auto)
559
657
  id: cut
560
- 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' && (env.RETRY_RUN != 'true' || steps.retry.outputs.retry == 'true')
658
+ 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' && (env.RETRY_RUN != 'true' || needs.decide.outputs.retry == 'true')
561
659
  env:
562
660
  EVENT: ${{ github.event_name }}
563
661
  RUN_SHA: ${{ github.event.workflow_run.head_sha }}