@futurelastic/colab-handbook 1.14.0-rc.9 → 1.14.0

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.
@@ -12,10 +12,8 @@
12
12
  #
13
13
  # HYBRID REPOS (a Python backend plus a Node/Vite frontend in one repo) are a real
14
14
  # and common shape here, and this template covers HALF of one. Do not copy the Node
15
- # template and graft a Python job into it: the header then lies about what the file
16
- # is, and that is exactly how a repo ended up with `python-version: "3.13"` hardcoded
17
- # — the Node template's own rule 1 forbids hardcoding, but there was nowhere to
18
- # declare a Python version, so the repo had no honest alternative. Instead:
15
+ # template and graft a Python job into it — the header then lies about what the file
16
+ # is, and the Python version ends up hardcoded. Instead:
19
17
  #
20
18
  # 1. copy THIS file to .github/workflows/ci.yml,
21
19
  # 2. copy the `build:` job out of ci-node.yml and paste it in alongside,
@@ -35,6 +33,13 @@
35
33
  # 4. Byte-compile — the cheapest possible "does it even parse" gate.
36
34
  # 5. Run lint / tests only if the repo has them, so a repo without a suite is not
37
35
  # forced to add placeholders to keep CI green.
36
+ #
37
+ # LIGHT LANE (#607): this file runs on every push and is what `colab ship` reads. Keep it
38
+ # fast — secret scan, build, typecheck/lint, the fast tests (target: under 5 minutes).
39
+ # The full suite, integration, e2e and load tests belong in the HEAVY lane,
40
+ # templates/ci-python-heavy.yml copied to .github/workflows/ci-heavy.yml: it runs nightly
41
+ # and on every release candidate/tag, never per merge. Tests are light unless marked heavy:
42
+ # the pytest marker `@pytest.mark.heavy` (register it in pytest.ini / pyproject.toml).
38
43
 
39
44
  name: CI
40
45
 
@@ -55,6 +60,10 @@ on:
55
60
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
56
61
  # merge into, and nothing looks broken (CONVENTIONS.md §7).
57
62
  branches: ['**']
63
+ # Optional (#607): skip documentation-only pushes here, if you like. `colab ship` decides a
64
+ # docs-only change from the diff and lands it without waiting for CI (CONVENTIONS.md §4,
65
+ # "Docs-only — no CI wait"), so a docs push with no run does not hold a merge.
66
+ # paths-ignore: ['**/*.md', 'docs/**']
58
67
  # No `pull_request:` here (#512). A branch with an open PR in this repository already
59
68
  # has a push run at the same head, and a `pull_request` run beside it doubled the CI
60
69
  # per commit while testing a merge ref instead of the sha that lands. Readers keep only
@@ -100,53 +109,16 @@ env:
100
109
  # jobs from different runs interleave, and trunk can wait behind branch runs.
101
110
  # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
102
111
  jobs:
103
- # Already tested at this sha? (#418) — the claim push.
104
- # A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
105
- # claim record), so the branch's first push sits on a sha trunk has usually already
106
- # run. Without this job that push re-runs the whole suite on a tested commit (~19% of
107
- # all runs, measured across five adopting repos). This job runs ONLY on a ref's first
108
- # push (`github.event.created`), checks nothing out, and asks one question: does THIS
109
- # workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
110
- # other job is skipped and the run concludes `success` — a branch-CI `green` that is
111
- # true, because the same workflow passed at the same sha. Anything else — trunk still
112
- # running, red, never run, `gh` missing, the API failing — and the suite runs as
113
- # before (fail-open: this job never fails the run). Every later push has
114
- # `created == false`, so a real commit always gets the full suite, with no extra hop.
115
- # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
116
- # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
117
- # §4, "Branch CI"). This job is the one that ends green.
118
- #
119
- # Already tested at this TREE? (#493) — the squash merge.
120
- # A ship squash-merges a branch whose green run already contained the current base, so
121
- # the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
122
- # sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
123
- # workflow have a green `push` run, on another ref of this repo, whose commit has THIS
124
- # exact tree? It confirms the tree through the git object, never only the run listing.
125
- # Yes → the suite is skipped and the run cites the run it relied on (a
126
- # `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
127
- # trees cover every committed byte, workflows and lockfiles included — NOT runner images,
128
- # unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
129
- # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
130
- # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
131
- # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
132
- # A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
133
- # asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
134
- # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
135
- # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
136
- # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
137
- #
138
- # Only documentation changed? (#570) — opt-in, `ci-docs-skip:` in .github/project.yml.
139
- # When the two modes above find nothing, a repo that declared `ci-docs-skip` at THIS sha
140
- # asks a third question: is every path changed since the base documentation, by the rule
141
- # `colab ship` applies (CONVENTIONS.md §2, the docs-only exception: .md/.mdx/.txt or under
142
- # docs/, never agent rules, config, a build input like requirements*.txt, a symlink, a
143
- # submodule or a binary), and does the base
144
- # have a green run of this workflow? The base is the merge base with trunk on a ref-creating
145
- # push, and the previous tip on a push to trunk. Yes → the suite is skipped and the run
146
- # leaves a `docs-only-skip` notice naming the base and its green run. A path the suite reads
147
- # (docs/api/ feeding a generator) is listed in `ci-docs-skip` and always runs the suite. Any
148
- # doubt (no opt-in, a red or unrun base, an API or fetch failure) runs the full suite. A run
149
- # skipped this way is never cited as tree-reuse proof: it skipped every job (#511).
112
+ # Already tested? This job is the one that concludes `success` when the suite is skipped: a
113
+ # run whose jobs ALL skip concludes `skipped`, which `colab ship` reads as not-green.
114
+ # - At this SHA (#418): on a ref's first push (a claim push), a green non-PR run of this
115
+ # workflow at the same sha means the suite already ran.
116
+ # - At this TREE (#493): on a push to trunk, a green push run elsewhere whose commit has the
117
+ # byte-identical tree (a squash of a branch that already contained its base) is reused and
118
+ # cited in a `tree-already-green` notice. `tree-reuse: off` in .github/project.yml opts out.
119
+ # A run that skipped a job (a trunk-only job skips on branches) is never reused (#511), so
120
+ # never put a trunk-only job (publish, deploy, release) behind this gate.
121
+ # Any doubt — no run, red, an API error — runs the full suite; this job never fails the run.
150
122
  dedupe:
151
123
  name: Already tested at this sha or tree?
152
124
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
@@ -157,7 +129,7 @@ jobs:
157
129
  actions: read
158
130
  contents: read
159
131
  outputs:
160
- tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
132
+ tested: ${{ steps.check.outputs.tested }}
161
133
  cited: ${{ steps.check.outputs.cited }}
162
134
  steps:
163
135
  - name: Look for a green run of this workflow at this sha or tree
@@ -260,160 +232,6 @@ jobs:
260
232
  fi
261
233
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
262
234
  [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
263
- # Docs-only (#570) — the two steps below run only when the step above found nothing.
264
- - name: Find the base a docs-only change would rely on
265
- id: docs_base
266
- if: steps.check.outputs.tested != 'true'
267
- env:
268
- GH_TOKEN: ${{ github.token }}
269
- REPO: ${{ github.repository }}
270
- RUN_ID: ${{ github.run_id }}
271
- SHA: ${{ github.sha }}
272
- BEFORE: ${{ github.event.before }}
273
- CREATED: ${{ github.event.created }}
274
- REF: ${{ github.ref }}
275
- REF_NAME: ${{ github.ref_name }}
276
- run: |
277
- base=
278
- # The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
279
- # doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
280
- optin() {
281
- local v items
282
- v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
283
- if [ -z "$v" ]; then
284
- items="$(printf '%s\n' "$DESC" | awk '/^ci-docs-skip[[:space:]]*:/{f=1;next} f&&/^[[:space:]]+-/{sub(/^[[:space:]]+-[[:space:]]*/,"");sub(/[[:space:]]+#.*$/,"");print;next} f&&/^[[:space:]]*(#.*)?$/{next} {f=0}')"
285
- [ -n "$items" ] || return 1
286
- elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
287
- v="${v#[}"; v="${v%]}"
288
- items="$(printf '%s' "$v" | tr ',' '\n')"
289
- else
290
- return 1
291
- fi
292
- EXCLUDE=
293
- while IFS= read -r it; do
294
- it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
295
- [ -n "$it" ] || continue
296
- case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
297
- printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
298
- EXCLUDE="$EXCLUDE ${it%/}"
299
- done <<< "$items"
300
- }
301
- if ! command -v gh >/dev/null 2>&1; then
302
- echo "gh is not installed on this runner — docs-only mode is off (#570)."
303
- elif [ "${REF#refs/heads/}" = "$REF" ]; then
304
- echo "$REF is not a branch — docs-only mode is off (#570)."
305
- elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
306
- echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
307
- elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
308
- echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
309
- elif ! optin; then
310
- echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
311
- else
312
- TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
313
- if [ -z "$TRUNK" ]; then
314
- echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
315
- elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
316
- # A new branch: the change is everything since it left trunk (the diff the squash lands).
317
- base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
318
- [ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
319
- elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
320
- base="$BEFORE" # a push to trunk: the change is what this push added
321
- else
322
- echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
323
- fi
324
- # The base must itself be green: a docs-only change cannot make a red suite green. The base
325
- # is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
326
- # branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
327
- # skipped on the branch, #511). Still running, red, or none: the full suite.
328
- if [ -n "$base" ]; then
329
- if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
330
- || ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
331
- --jq "[.workflow_runs[] | select(.id != $RUN_ID and .head_branch == \"$TRUNK\" and .head_repository.full_name == \"$REPO\")] | sort_by(.created_at) | last | if . != null and .status == \"completed\" and .conclusion == \"success\" then .html_url else empty end" 2>/dev/null)"; then
332
- echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
333
- base=
334
- elif [ -z "$URL" ]; then
335
- echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
336
- base=
337
- fi
338
- fi
339
- fi
340
- if [ -n "$base" ]; then
341
- echo "base=$base" >> "$GITHUB_OUTPUT"
342
- echo "base_run=$URL" >> "$GITHUB_OUTPUT"
343
- echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
344
- fi
345
- - name: Is every changed path documentation?
346
- id: docs
347
- if: steps.docs_base.outputs.base != ''
348
- env:
349
- GH_TOKEN: ${{ github.token }}
350
- SERVER_URL: ${{ github.server_url }}
351
- REPO: ${{ github.repository }}
352
- SHA: ${{ github.sha }}
353
- BASE: ${{ steps.docs_base.outputs.base }}
354
- BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
355
- EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
356
- run: |
357
- tested=false
358
- # Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
359
- # §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
360
- # Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
361
- reason() {
362
- local p="$1" base dir x
363
- base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
364
- case "$p" in \"*) echo "quoted path"; return ;; esac
365
- for x in $EXCLUDE; do
366
- case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
367
- done
368
- case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
369
- # A build input despite the extension: the cure rule's Python manifest (any case), a pip
370
- # constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
371
- lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
372
- case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
373
- case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
374
- [ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
375
- case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
376
- case "$p" in docs/*) return ;; esac
377
- case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
378
- echo "not .md/.mdx/.txt and not under docs/"
379
- }
380
- # Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
381
- G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
382
- AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
383
- if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
384
- && git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
385
- && git -C "$G" config http.extraheader "$AUTH" \
386
- && git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
387
- echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
388
- elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
389
- || ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
390
- echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
391
- elif [ -z "$RAW" ]; then
392
- echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
393
- else
394
- bad=; n=0
395
- while IFS= read -r line; do
396
- meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
397
- why="$(reason "$p")"
398
- set -- $meta
399
- case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
400
- case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
401
- [ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
402
- done <<< "$RAW"
403
- while IFS=$'\t' read -r a d p; do
404
- if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
405
- done <<< "$NUM"
406
- if [ -n "$bad" ]; then
407
- echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
408
- else
409
- tested=true
410
- echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
411
- echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
412
- echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
413
- fi
414
- fi
415
- rm -rf "$G"
416
- echo "tested=$tested" >> "$GITHUB_OUTPUT"
417
235
 
418
236
  gitleaks:
419
237
  name: Secret scan (gitleaks)
@@ -743,4 +561,5 @@ jobs:
743
561
 
744
562
  - name: Test (pytest)
745
563
  if: steps.tools.outputs.pytest == 'true'
746
- run: python -m pytest -q
564
+ # Everything not marked heavy; ci-heavy.yml runs the rest. Exit 5 = no test selected.
565
+ run: python -m pytest -q -m "not heavy" || [ $? -eq 5 ]
@@ -517,9 +517,78 @@ jobs:
517
517
  fi
518
518
  fi
519
519
 
520
+ # THE HEAVY LANE AT EVERY CANDIDATE (#607). A candidate is an official build, so the heavy
521
+ # lane (ci-heavy.yml, from templates/ci-<stack>-heavy.yml) starts at its exact commit now and
522
+ # has the whole test period to finish; the finalize step below waits for its green. A dispatch,
523
+ # not `workflow_call`: a called workflow's jobs run inside THIS run, which colab ignores as its
524
+ # own (#425), so the verdict would be invisible at the sha. No heavy lane here → nothing to do.
525
+ - name: Start the heavy lane at the new candidate
526
+ if: steps.cut.outputs.tag != ''
527
+ env:
528
+ GH_TOKEN: ${{ github.token }}
529
+ TAG: ${{ steps.cut.outputs.tag }}
530
+ HEAVY_WORKFLOW: ci-heavy.yml # EDIT: the heavy lane's file name, if you named it otherwise.
531
+ run: |
532
+ set -uo pipefail
533
+ eval "$RETRY_TRANSIENT"
534
+ if [ ! -f ".github/workflows/$HEAVY_WORKFLOW" ]; then
535
+ echo "No .github/workflows/$HEAVY_WORKFLOW — no heavy lane to start."
536
+ elif retry_transient gh workflow run "$HEAVY_WORKFLOW" --ref "$TAG" -f ref="$TAG"; then
537
+ echo "Dispatched $HEAVY_WORKFLOW at $TAG — a final needs its green run at this commit." | tee -a "$GITHUB_STEP_SUMMARY"
538
+ else
539
+ echo "::warning::could not dispatch $HEAVY_WORKFLOW at $TAG — the finalize step dispatches it again"
540
+ fi
541
+
542
+ # THE HEAVY LANE GATES A FINAL (#607): a final is cut only when the heavy lane has a green run
543
+ # at the candidate's exact commit. None yet → it is dispatched (unless one is running) and this
544
+ # run does not finalize; a red one refuses until a human re-runs it green or cuts a new
545
+ # candidate. A refusal is not a failure: the step stays green. No heavy lane here → no gate.
546
+ - name: Heavy lane green at the candidate?
547
+ id: heavy
548
+ if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
549
+ env:
550
+ GH_TOKEN: ${{ github.token }}
551
+ HEAVY_WORKFLOW: ci-heavy.yml # EDIT: the same name as in the step that starts it.
552
+ run: |
553
+ set -uo pipefail
554
+ eval "$RETRY_TRANSIENT"
555
+ if [ ! -f ".github/workflows/$HEAVY_WORKFLOW" ]; then
556
+ echo "No .github/workflows/$HEAVY_WORKFLOW — no heavy lane gates the final."
557
+ exit 0
558
+ fi
559
+ OUT="$RUNNER_TEMP/finalize-dry.json"
560
+ retry_transient node "$COLAB" release finalize --auto --dry --json > "$OUT" || true
561
+ TAG="$(jq -r '.candidate.tag // empty' "$OUT" 2>/dev/null || true)"
562
+ SHA="$(jq -r '.candidate.sha // empty' "$OUT" 2>/dev/null || true)"
563
+ if [ -z "$SHA" ]; then
564
+ echo "No candidate to finalize — nothing for the heavy lane to gate."
565
+ exit 0
566
+ fi
567
+ if ! RUNS="$(retry_transient gh run list --workflow "$HEAVY_WORKFLOW" --commit "$SHA" --json status,conclusion,url -L 20)"; then
568
+ echo "::warning::cannot read $HEAVY_WORKFLOW runs at $SHA — not finalizing in this run"
569
+ echo "ok=false" >> "$GITHUB_OUTPUT"
570
+ exit 0
571
+ fi
572
+ if jq -e 'any(.[]; .conclusion == "success")' <<< "$RUNS" > /dev/null; then
573
+ echo "Heavy lane green at $TAG ($SHA): $(jq -r '[.[] | select(.conclusion == "success")][0].url' <<< "$RUNS")" | tee -a "$GITHUB_STEP_SUMMARY"
574
+ exit 0
575
+ fi
576
+ echo "ok=false" >> "$GITHUB_OUTPUT"
577
+ if jq -e 'any(.[]; .status != "completed")' <<< "$RUNS" > /dev/null; then
578
+ echo "Heavy lane still running at $TAG — no final in this run." | tee -a "$GITHUB_STEP_SUMMARY"
579
+ elif jq -e 'length > 0' <<< "$RUNS" > /dev/null; then
580
+ echo "::warning::$TAG not finalized: the heavy lane is red at $SHA ($(jq -r '.[0].url' <<< "$RUNS")) — re-run it green, or cut a new candidate"
581
+ elif [ "${DRY_RUN:-false}" = "true" ]; then
582
+ echo "Dry run — would start $HEAVY_WORKFLOW at $TAG (no run at $SHA yet)." | tee -a "$GITHUB_STEP_SUMMARY"
583
+ elif retry_transient gh workflow run "$HEAVY_WORKFLOW" --ref "$TAG" -f ref="$TAG"; then
584
+ echo "No heavy run at $TAG yet — dispatched $HEAVY_WORKFLOW; a later run finalizes on its green." | tee -a "$GITHUB_STEP_SUMMARY"
585
+ else
586
+ echo "::warning::$TAG not finalized: no heavy run at $SHA and $HEAVY_WORKFLOW could not be dispatched"
587
+ fi
588
+
520
589
  - name: Finalize the newest clean candidate (colab release finalize --auto)
521
590
  id: finalize
522
- if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
591
+ if: ((github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch') && steps.heavy.outputs.ok != 'false'
523
592
  run: |
524
593
  set -uo pipefail
525
594
  eval "$RETRY_TRANSIENT"
@@ -8,9 +8,15 @@
8
8
  #
9
9
  # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
10
10
  #
11
- # TIER A ONLY. Under the tiered branch model, a Tier A release is: merge dev -> main,
12
- # heavy CI on main goes green, tag v*.*.*. The tag is what triggers deployment. This
13
- # workflow runs alongside that deploy and produces the human-facing record of the release.
11
+ # TIER A ONLY. Under the tiered branch model, a Tier A release is: merge dev -> main, tag
12
+ # v*.*.*. The tag is what triggers deployment. This workflow runs alongside that deploy and
13
+ # produces the human-facing record of the release.
14
+ #
15
+ # THE HEAVY LANE GATES THE RECORD (#607). The `heavy` job below calls ci-heavy.yml (copied
16
+ # from templates/ci-<stack>-heavy.yml) at the tag's commit, and `release` publishes only when
17
+ # it is green — a red heavy lane leaves no release record. EDIT: your deploy workflow fires on
18
+ # the same tag independently; to hold the deploy too, give it the same `heavy` job and `needs:`.
19
+ # No heavy lane in this repo? Delete the `heavy` job and the `needs:` line.
14
20
  #
15
21
  # Do NOT copy this into a Tier C repo. Tier C has no tag step — promotion dev -> main
16
22
  # IS the deploy — so this workflow would never fire. Tier B has no production at all.
@@ -88,8 +94,19 @@ env:
88
94
  # tag as a full release. Pre-release is derived from the tag name in the step below.
89
95
 
90
96
  jobs:
97
+ heavy:
98
+ name: Heavy lane at this tag
99
+ uses: ./.github/workflows/ci-heavy.yml
100
+ with:
101
+ ref: ${{ github.ref_name }}
102
+ permissions:
103
+ actions: read
104
+ contents: read
105
+ issues: write # only its nightly report job writes, and it never runs on a tag
106
+
91
107
  release:
92
108
  name: Publish release
109
+ needs: heavy
93
110
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
94
111
  permissions:
95
112
  # Required to create the release. Nothing else is needed — keep it minimal.