@futurelastic/colab-handbook 1.14.0-rc.13 → 1.14.0-rc.15

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.
@@ -30,23 +30,19 @@
30
30
  # container). Every case below was measured, and the engines disagree on several of
31
31
  # them — so either engine alone passes a migration the other refuses:
32
32
  #
33
- # - A down() whose statements sqlite cannot run: only the sqlite leg goes red —
34
- # and only if down() is ever executed, which nothing else in CI does.
35
- # - A down() that does not undo its up(): the schema after the second migrate
36
- # differs from the first, on either leg.
37
- # - NOT NULL without a default: sqlite refuses the ALTER when the table holds
38
- # rows; MariaDB accepts it and silently fills '' into every existing row. Only
39
- # the sqlite leg goes red.
40
- # - A foreign key added over orphan rows, ->change() silently dropping a modifier
41
- # it did not restate (nullable, default, unsigned), lossy numeric conversion:
42
- # the deploy engine's strict mode refuses these. sqlite catches some of them
43
- # too, through its table rebuild — never count on it for the rest.
44
- #
45
- # The last two bullets fire ONLY when rows exist — on an empty table every one of
46
- # them passes on both engines. Set ROUNDTRIP_SEEDER below, or they go unchecked.
33
+ # Which defects each leg catches, and why the last ones need rows (ROUNDTRIP_SEEDER below):
34
+ # templates/README.md, "Migration round-trip". It stays in this light lane on purpose: a
35
+ # `migration-grant: reviewer` repo's ship reads this job by name (the R condition, #494).
47
36
  #
48
37
  # Not gated on RUN_TESTS: a bad migration is cheapest to fix on the branch that adds or
49
38
  # modifies it, so this runs on every push, not only on main.
39
+ #
40
+ # LIGHT LANE (#607): this file runs on every push and is what `colab ship` reads. Keep it
41
+ # fast — secret scan, build, typecheck/lint, the fast tests (target: under 5 minutes).
42
+ # The full suite, integration, e2e and load tests belong in the HEAVY lane,
43
+ # templates/ci-laravel-heavy.yml copied to .github/workflows/ci-heavy.yml: it runs nightly
44
+ # and on every release candidate/tag, never per merge. Tests are light unless marked heavy:
45
+ # the Pest/PHPUnit group `heavy` (`->group('heavy')` or `#[Group('heavy')]`).
50
46
 
51
47
  name: CI
52
48
 
@@ -67,6 +63,10 @@ on:
67
63
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
68
64
  # merge into, and nothing looks broken (CONVENTIONS.md §7).
69
65
  branches: ['**']
66
+ # Optional (#607): skip documentation-only pushes here, if you like. `colab ship` decides a
67
+ # docs-only change from the diff and lands it without waiting for CI (CONVENTIONS.md §4,
68
+ # "Docs-only — no CI wait"), so a docs push with no run does not hold a merge.
69
+ # paths-ignore: ['**/*.md', 'docs/**']
70
70
  # No `pull_request:` here (#512). A branch with an open PR in this repository already
71
71
  # has a push run at the same head, and a `pull_request` run beside it doubled the CI
72
72
  # per commit while testing a merge ref instead of the sha that lands. Readers keep only
@@ -123,53 +123,16 @@ env:
123
123
  # jobs from different runs interleave, and trunk can wait behind branch runs.
124
124
  # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
125
125
  jobs:
126
- # Already tested at this sha? (#418) — the claim push.
127
- # A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
128
- # claim record), so the branch's first push sits on a sha trunk has usually already
129
- # run. Without this job that push re-runs the whole suite on a tested commit (~19% of
130
- # all runs, measured across five adopting repos). This job runs ONLY on a ref's first
131
- # push (`github.event.created`), checks nothing out, and asks one question: does THIS
132
- # workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
133
- # other job is skipped and the run concludes `success` — a branch-CI `green` that is
134
- # true, because the same workflow passed at the same sha. Anything else — trunk still
135
- # running, red, never run, `gh` missing, the API failing — and the suite runs as
136
- # before (fail-open: this job never fails the run). Every later push has
137
- # `created == false`, so a real commit always gets the full suite, with no extra hop.
138
- # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
139
- # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
140
- # §4, "Branch CI"). This job is the one that ends green.
141
- #
142
- # Already tested at this TREE? (#493) — the squash merge.
143
- # A ship squash-merges a branch whose green run already contained the current base, so
144
- # the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
145
- # sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
146
- # workflow have a green `push` run, on another ref of this repo, whose commit has THIS
147
- # exact tree? It confirms the tree through the git object, never only the run listing.
148
- # Yes → the suite is skipped and the run cites the run it relied on (a
149
- # `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
150
- # trees cover every committed byte, workflows and lockfiles included — NOT runner images,
151
- # unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
152
- # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
153
- # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
154
- # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
155
- # A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
156
- # asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
157
- # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
158
- # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
159
- # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
160
- #
161
- # Only documentation changed? (#570) — opt-in, `ci-docs-skip:` in .github/project.yml.
162
- # When the two modes above find nothing, a repo that declared `ci-docs-skip` at THIS sha
163
- # asks a third question: is every path changed since the base documentation, by the rule
164
- # `colab ship` applies (CONVENTIONS.md §2, the docs-only exception: .md/.mdx/.txt or under
165
- # docs/, never agent rules, config, a build input like requirements*.txt, a symlink, a
166
- # submodule or a binary), and does the base
167
- # have a green run of this workflow? The base is the merge base with trunk on a ref-creating
168
- # push, and the previous tip on a push to trunk. Yes → the suite is skipped and the run
169
- # leaves a `docs-only-skip` notice naming the base and its green run. A path the suite reads
170
- # (docs/api/ feeding a generator) is listed in `ci-docs-skip` and always runs the suite. Any
171
- # doubt (no opt-in, a red or unrun base, an API or fetch failure) runs the full suite. A run
172
- # skipped this way is never cited as tree-reuse proof: it skipped every job (#511).
126
+ # Already tested? This job is the one that concludes `success` when the suite is skipped: a
127
+ # run whose jobs ALL skip concludes `skipped`, which `colab ship` reads as not-green.
128
+ # - At this SHA (#418): on a ref's first push (a claim push), a green non-PR run of this
129
+ # workflow at the same sha means the suite already ran.
130
+ # - At this TREE (#493): on a push to trunk, a green push run elsewhere whose commit has the
131
+ # byte-identical tree (a squash of a branch that already contained its base) is reused and
132
+ # cited in a `tree-already-green` notice. `tree-reuse: off` in .github/project.yml opts out.
133
+ # A run that skipped a job (a trunk-only job skips on branches) is never reused (#511), so
134
+ # never put a trunk-only job (publish, deploy, release) behind this gate.
135
+ # Any doubt — no run, red, an API error — runs the full suite; this job never fails the run.
173
136
  dedupe:
174
137
  name: Already tested at this sha or tree?
175
138
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
@@ -180,7 +143,7 @@ jobs:
180
143
  actions: read
181
144
  contents: read
182
145
  outputs:
183
- tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
146
+ tested: ${{ steps.check.outputs.tested }}
184
147
  cited: ${{ steps.check.outputs.cited }}
185
148
  steps:
186
149
  - name: Look for a green run of this workflow at this sha or tree
@@ -283,160 +246,6 @@ jobs:
283
246
  fi
284
247
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
285
248
  [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
286
- # Docs-only (#570) — the two steps below run only when the step above found nothing.
287
- - name: Find the base a docs-only change would rely on
288
- id: docs_base
289
- if: steps.check.outputs.tested != 'true'
290
- env:
291
- GH_TOKEN: ${{ github.token }}
292
- REPO: ${{ github.repository }}
293
- RUN_ID: ${{ github.run_id }}
294
- SHA: ${{ github.sha }}
295
- BEFORE: ${{ github.event.before }}
296
- CREATED: ${{ github.event.created }}
297
- REF: ${{ github.ref }}
298
- REF_NAME: ${{ github.ref_name }}
299
- run: |
300
- base=
301
- # The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
302
- # doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
303
- optin() {
304
- local v items
305
- v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
306
- if [ -z "$v" ]; then
307
- 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}')"
308
- [ -n "$items" ] || return 1
309
- elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
310
- v="${v#[}"; v="${v%]}"
311
- items="$(printf '%s' "$v" | tr ',' '\n')"
312
- else
313
- return 1
314
- fi
315
- EXCLUDE=
316
- while IFS= read -r it; do
317
- it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
318
- [ -n "$it" ] || continue
319
- case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
320
- printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
321
- EXCLUDE="$EXCLUDE ${it%/}"
322
- done <<< "$items"
323
- }
324
- if ! command -v gh >/dev/null 2>&1; then
325
- echo "gh is not installed on this runner — docs-only mode is off (#570)."
326
- elif [ "${REF#refs/heads/}" = "$REF" ]; then
327
- echo "$REF is not a branch — docs-only mode is off (#570)."
328
- elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
329
- echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
330
- elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
331
- echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
332
- elif ! optin; then
333
- echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
334
- else
335
- TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
336
- if [ -z "$TRUNK" ]; then
337
- echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
338
- elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
339
- # A new branch: the change is everything since it left trunk (the diff the squash lands).
340
- base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
341
- [ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
342
- elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
343
- base="$BEFORE" # a push to trunk: the change is what this push added
344
- else
345
- echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
346
- fi
347
- # The base must itself be green: a docs-only change cannot make a red suite green. The base
348
- # is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
349
- # branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
350
- # skipped on the branch, #511). Still running, red, or none: the full suite.
351
- if [ -n "$base" ]; then
352
- if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
353
- || ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
354
- --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
355
- echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
356
- base=
357
- elif [ -z "$URL" ]; then
358
- echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
359
- base=
360
- fi
361
- fi
362
- fi
363
- if [ -n "$base" ]; then
364
- echo "base=$base" >> "$GITHUB_OUTPUT"
365
- echo "base_run=$URL" >> "$GITHUB_OUTPUT"
366
- echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
367
- fi
368
- - name: Is every changed path documentation?
369
- id: docs
370
- if: steps.docs_base.outputs.base != ''
371
- env:
372
- GH_TOKEN: ${{ github.token }}
373
- SERVER_URL: ${{ github.server_url }}
374
- REPO: ${{ github.repository }}
375
- SHA: ${{ github.sha }}
376
- BASE: ${{ steps.docs_base.outputs.base }}
377
- BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
378
- EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
379
- run: |
380
- tested=false
381
- # Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
382
- # §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
383
- # Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
384
- reason() {
385
- local p="$1" base dir x
386
- base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
387
- case "$p" in \"*) echo "quoted path"; return ;; esac
388
- for x in $EXCLUDE; do
389
- case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
390
- done
391
- case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
392
- # A build input despite the extension: the cure rule's Python manifest (any case), a pip
393
- # constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
394
- lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
395
- case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
396
- case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
397
- [ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
398
- case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
399
- case "$p" in docs/*) return ;; esac
400
- case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
401
- echo "not .md/.mdx/.txt and not under docs/"
402
- }
403
- # Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
404
- G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
405
- AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
406
- if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
407
- && git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
408
- && git -C "$G" config http.extraheader "$AUTH" \
409
- && git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
410
- echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
411
- elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
412
- || ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
413
- echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
414
- elif [ -z "$RAW" ]; then
415
- echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
416
- else
417
- bad=; n=0
418
- while IFS= read -r line; do
419
- meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
420
- why="$(reason "$p")"
421
- set -- $meta
422
- case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
423
- case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
424
- [ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
425
- done <<< "$RAW"
426
- while IFS=$'\t' read -r a d p; do
427
- if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
428
- done <<< "$NUM"
429
- if [ -n "$bad" ]; then
430
- echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
431
- else
432
- tested=true
433
- echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
434
- echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
435
- echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
436
- fi
437
- fi
438
- rm -rf "$G"
439
- echo "tested=$tested" >> "$GITHUB_OUTPUT"
440
249
 
441
250
  gitleaks:
442
251
  name: Secret scan (gitleaks)
@@ -833,10 +642,10 @@ jobs:
833
642
  if: steps.tier.outputs.run_tests == 'true'
834
643
  run: |
835
644
  if [ -f vendor/bin/pest ]; then
836
- vendor/bin/pest --ci
645
+ vendor/bin/pest --ci --exclude-group=heavy # light lane; ci-heavy.yml runs the full suite
837
646
  elif [ -f vendor/bin/phpunit ]; then
838
647
  echo "::notice::No Pest binary — falling back to PHPUnit."
839
- vendor/bin/phpunit
648
+ vendor/bin/phpunit --exclude-group=heavy
840
649
  else
841
650
  echo "::error::RUN_TESTS is true but neither vendor/bin/pest nor vendor/bin/phpunit exists. Add a test runner, or set RUN_TESTS: false."
842
651
  exit 1
@@ -0,0 +1,289 @@
1
+ # CI heavy lane (Node) — TEMPLATE. Copy me into your repo at .github/workflows/ci-heavy.yml,
2
+ # beside ci.yml (copied from ci-node.yml). Guidance, not a dependency:
3
+ # you own the copy (CONVENTIONS.md §7).
4
+ #
5
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
6
+ #
7
+ # HEAVY LANE (#607): the whole suite, including tests marked heavy, plus anything too slow for
8
+ # every merge (integration, browser/e2e, load). The light lane (ci.yml) runs on every push and
9
+ # is the only lane `colab ship` reads. This one runs:
10
+ # - NIGHTLY, on trunk's tip. Skipped when trunk has not moved since the last green nightly.
11
+ # A red nightly opens one `trunk-red` issue naming the commit range that could have caused
12
+ # it. It never blocks a merge.
13
+ # - On every OFFICIAL BUILD: release-tag.yml calls this file and publishes only when it is
14
+ # green; release-auto.yml dispatches it at each candidate and finalizes only when it is
15
+ # green at that exact sha.
16
+ # - BY HAND: Actions → "CI (heavy)" → Run workflow, with a ref.
17
+ # Heavy is opt-in per test; an unmarked test is light. The marker:
18
+ # a `test:heavy` script in package.json (e.g. over `*.heavy.test.*` files). `npm test`
19
+ # stays light; this lane runs both.
20
+ #
21
+ # Deliberately NOT triggered by push or pull_request: a run of this workflow must never count as
22
+ # a merge verdict (tools/lib/verify-runs.js sets schedule and dispatch runs aside).
23
+ # No concurrency block: a heavy run is never cancelled — a release may be waiting on it.
24
+
25
+ name: CI (heavy)
26
+
27
+ on:
28
+ schedule:
29
+ - cron: "23 2 * * *" # EDIT: nightly, UTC. Keep the cron in this one place.
30
+ workflow_dispatch:
31
+ inputs:
32
+ ref:
33
+ description: "Branch, tag or sha to test (empty = trunk's tip)"
34
+ required: false
35
+ default: ""
36
+ workflow_call:
37
+ inputs:
38
+ ref:
39
+ description: "Branch, tag or sha to test"
40
+ type: string
41
+ required: true
42
+
43
+ permissions: {}
44
+
45
+ env:
46
+ # EDIT: this repo's trunk (`trunk:` in .github/project.yml). A schedule always starts on the
47
+ # default branch; the nightly tests THIS branch's tip.
48
+ TRUNK: main
49
+
50
+ jobs:
51
+ # Resolves the one commit this run tests, and decides whether to test it. This job is the one
52
+ # that concludes `success` when the nightly skips: a run whose jobs all skip reads as not-green.
53
+ plan:
54
+ name: What to test
55
+ runs-on: ubuntu-latest # EDIT: needs `gh` (GitHub-hosted images have it).
56
+ timeout-minutes: 5
57
+ permissions:
58
+ actions: read
59
+ contents: read
60
+ outputs:
61
+ sha: ${{ steps.plan.outputs.sha }}
62
+ run: ${{ steps.plan.outputs.run }}
63
+ since: ${{ steps.plan.outputs.since }}
64
+ steps:
65
+ - name: Resolve the commit; skip a nightly on an unmoved trunk
66
+ id: plan
67
+ env:
68
+ GH_TOKEN: ${{ github.token }}
69
+ EVENT: ${{ github.event_name }}
70
+ REF: ${{ inputs.ref }}
71
+ REPO: ${{ github.repository }}
72
+ WORKFLOW_REF: ${{ github.workflow_ref }}
73
+ run: |
74
+ set -uo pipefail
75
+ target="${REF:-$TRUNK}"
76
+ if ! sha="$(gh api "repos/$REPO/commits/$target" --jq .sha)" || [ -z "$sha" ]; then
77
+ echo "::error::cannot resolve '$target' to a commit"
78
+ exit 1
79
+ fi
80
+ echo "sha=$sha" >> "$GITHUB_OUTPUT"
81
+ run=true; since=""
82
+ if [ "$EVENT" = "schedule" ]; then
83
+ # The last green nightly's tested commit, read from its `Full suite @ <sha>` job.
84
+ # Any read error leaves `since` empty, and the suite runs.
85
+ wf="${WORKFLOW_REF%@*}"; wf="${wf##*/}"
86
+ for id in $(gh api "repos/$REPO/actions/workflows/$wf/runs?event=schedule&status=success&per_page=10" \
87
+ --jq '.workflow_runs[].id' 2>/dev/null); do
88
+ since="$(gh api "repos/$REPO/actions/runs/$id/jobs" \
89
+ --jq '[.jobs[] | select(.conclusion == "success" and (.name | startswith("Full suite @ "))) | .name | ltrimstr("Full suite @ ")][0] // ""' 2>/dev/null || true)"
90
+ [ -z "$since" ] || break
91
+ done
92
+ if [ "$since" = "$sha" ]; then
93
+ run=false
94
+ echo "::notice title=heavy-skipped::$TRUNK has not moved since the last green nightly ($sha)"
95
+ fi
96
+ fi
97
+ echo "run=$run" >> "$GITHUB_OUTPUT"
98
+ echo "since=$since" >> "$GITHUB_OUTPUT"
99
+ echo "Heavy lane: ${run} at \`$sha\`${since:+ (last green nightly: \`$since\`)}" >> "$GITHUB_STEP_SUMMARY"
100
+
101
+ heavy:
102
+ # The tested sha is in the job name: the next nightly reads it back to decide whether trunk moved.
103
+ name: Full suite @ ${{ needs.plan.outputs.sha }}
104
+ needs: plan
105
+ if: ${{ needs.plan.outputs.run == 'true' }}
106
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
107
+ timeout-minutes: 120 # EDIT: well above YOUR heavy p99; the default is 360.
108
+ permissions:
109
+ contents: read
110
+ defaults:
111
+ run:
112
+ # EDIT: the same directory as ci.yml's build job.
113
+ working-directory: .
114
+ steps:
115
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
116
+ with:
117
+ ref: ${{ needs.plan.outputs.sha }}
118
+ persist-credentials: false
119
+
120
+ # Toolchain and install: the same steps as ci.yml's build job, so both lanes resolve the
121
+ # same versions. Keep them in step when you edit either.
122
+ # ---------------------------------------------------------------------------
123
+ # Toolchain resolution. Precedence, highest first:
124
+ # 1. .github/project.yml -> node: <version>
125
+ # 2. .nvmrc, else package.json -> engines.node
126
+ # 3. FAIL.
127
+ #
128
+ # There is deliberately NO fallback default. A silent default is exactly how a
129
+ # repo here ended up building on Node 20 in CI while deploying on Node 22 —
130
+ # CI was green and proved nothing about what actually shipped. If the version
131
+ # is not declared anywhere, that is a bug in the repo, and the build says so.
132
+ # ---------------------------------------------------------------------------
133
+ - name: Resolve Node version
134
+ id: toolchain
135
+ if: hashFiles('package.json') != ''
136
+ run: |
137
+ set -euo pipefail
138
+
139
+ # Normalise "^22", ">=22.1", "v22", "22.x" -> "22.1" / "22". setup-node
140
+ # accepts a partial version and picks the newest matching release.
141
+ normalise() {
142
+ printf '%s' "$1" \
143
+ | tr -d '"' \
144
+ | sed -E 's/^[^0-9]*//' \
145
+ | sed -E 's/[[:space:]].*$//' \
146
+ | sed -E 's/\.x$//' \
147
+ | sed -E 's/[^0-9.].*$//' \
148
+ | sed -E 's/\.$//'
149
+ }
150
+
151
+ NODE_VERSION=""
152
+ SOURCE=""
153
+
154
+ # 1. project.yml wins. Flat `node: 22` mapping; good enough, this file is
155
+ # a handful of keys by design.
156
+ if [ -f .github/project.yml ]; then
157
+ V="$(sed -nE 's/^[[:space:]]*node:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml | head -1 || true)"
158
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
159
+ NODE_VERSION="$(normalise "$V")"; SOURCE=".github/project.yml (node:)"
160
+ fi
161
+ fi
162
+
163
+ # 2a. .nvmrc
164
+ if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
165
+ V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
166
+ if [ -n "$V" ]; then
167
+ NODE_VERSION="$(normalise "$V")"; SOURCE=".nvmrc"
168
+ fi
169
+ fi
170
+
171
+ # 2b. package.json -> engines.node
172
+ if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
173
+ V=""
174
+ if command -v node >/dev/null 2>&1; then
175
+ V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
176
+ elif command -v python3 >/dev/null 2>&1; then
177
+ V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
178
+ fi
179
+ if [ -n "$V" ]; then
180
+ NODE_VERSION="$(normalise "$V")"; SOURCE="package.json (engines.node)"
181
+ fi
182
+ fi
183
+
184
+ # 3. No declared source -> stop. Do not guess.
185
+ if [ -z "$NODE_VERSION" ]; then
186
+ echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
187
+ {
188
+ echo ""
189
+ echo "Declare it in ONE of these places (checked in this order):"
190
+ echo " 1. .github/project.yml -> node: \"22\" (preferred: one descriptor for the whole repo)"
191
+ echo " 2. .nvmrc -> 22 (also drives local dev via nvm/fnm)"
192
+ echo " or package.json -> \"engines\": { \"node\": \">=22\" }"
193
+ echo ""
194
+ echo "Pick the version your DEPLOY target runs. CI on a different major than"
195
+ echo "production proves nothing."
196
+ } >&2
197
+ exit 1
198
+ fi
199
+
200
+ echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
201
+ echo "Node $NODE_VERSION (resolved from: $SOURCE)"
202
+ echo "Node **$NODE_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
203
+
204
+ # Package cache (#571): on only on a GitHub-hosted runner AND with package-lock.json
205
+ # present. Both halves are load-bearing:
206
+ # - No lockfile → setup-node's `cache:` fails the step outright ("Dependencies lock
207
+ # file is not found"), and this template allows a repo without one.
208
+ # - Self-hosted → off. A persistent runner already keeps ~/.npm between jobs; a
209
+ # remote cache on top was measured as a loss, not a saving (#512).
210
+ # npm only: `cache: pnpm` needs pnpm on PATH before this step, and the install step
211
+ # below enables it through corepack afterwards. `package-manager-cache` is pinned to
212
+ # the same condition so setup-node's automatic `packageManager` caching cannot switch
213
+ # it back on where the condition says off.
214
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, replace
215
+ # both expressions with '' and false. If the app is not at the root, point the
216
+ # hashFiles() and a `cache-dependency-path:` at its package-lock.json.
217
+ - name: Setup Node
218
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
219
+ if: hashFiles('package.json') != ''
220
+ with:
221
+ node-version: ${{ steps.toolchain.outputs.node-version }}
222
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
223
+ package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
224
+
225
+ - name: Install dependencies
226
+ if: hashFiles('package.json') != ''
227
+ run: |
228
+ # Lockfile decides the package manager. `npm ci` / `--frozen-lockfile` are
229
+ # intentional: CI must fail on a stale lockfile rather than silently resolve
230
+ # a different dependency tree than the developer had.
231
+ if [ -f pnpm-lock.yaml ]; then
232
+ corepack enable
233
+ pnpm install --frozen-lockfile
234
+ elif [ -f package-lock.json ]; then
235
+ npm ci
236
+ else
237
+ echo "::warning::No lockfile found — falling back to 'npm install'. Commit a lockfile so CI is reproducible."
238
+ npm install
239
+ fi
240
+
241
+ - name: Test (the whole suite)
242
+ run: |
243
+ # `npm test` (light) and then `test:heavy`, if this repo has one.
244
+ has() { node -e "const s=(require('./package.json').scripts)||{};process.exit(s['$1']?0:1)" 2>/dev/null; }
245
+ if has test; then npm test; else echo "::notice::No 'test' script in package.json."; fi
246
+ if has test:heavy; then npm run test:heavy; else echo "::notice::No 'test:heavy' script — nothing is marked heavy."; fi
247
+ # EDIT: integration, browser/e2e or load jobs go here, or as jobs of their own with
248
+ # `needs: plan` and the same `if:` and checkout ref as this one.
249
+
250
+ # A red NIGHTLY is a trunk finding, never a merge block: one open issue per lane. An open issue
251
+ # with the same title suppresses a new one; an issue list that cannot be read files nothing and
252
+ # fails this job, so a silent miss is never mistaken for "already reported".
253
+ report:
254
+ name: Report a red nightly
255
+ needs: [plan, heavy]
256
+ if: ${{ always() && github.event_name == 'schedule' && needs.heavy.result == 'failure' }}
257
+ runs-on: ubuntu-latest # EDIT: needs `gh`.
258
+ timeout-minutes: 5
259
+ permissions:
260
+ issues: write
261
+ steps:
262
+ - name: File one trunk-red issue
263
+ env:
264
+ GH_TOKEN: ${{ github.token }}
265
+ REPO: ${{ github.repository }}
266
+ SHA: ${{ needs.plan.outputs.sha }}
267
+ SINCE: ${{ needs.plan.outputs.since }}
268
+ WORKFLOW: ${{ github.workflow }}
269
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
270
+ run: |
271
+ set -uo pipefail
272
+ title="Nightly heavy lane red: $WORKFLOW"
273
+ if ! open="$(gh issue list -R "$REPO" --state open --search "\"$title\" in:title" --json number,title \
274
+ --jq "[.[] | select(.title == \"$title\")][0].number // \"\"")"; then
275
+ echo "::error::cannot read this repo's issues — nothing filed; the red run is the only report"
276
+ exit 1
277
+ fi
278
+ if [ -n "$open" ]; then
279
+ echo "::notice::#$open already reports this lane red — not filing another."
280
+ exit 0
281
+ fi
282
+ if [ -n "$SINCE" ]; then
283
+ range="[\`${SINCE:0:12}..${SHA:0:12}\`]($GITHUB_SERVER_URL/$REPO/compare/$SINCE...$SHA) — the commits since the last green nightly"
284
+ else
285
+ range="up to \`${SHA:0:12}\` — no green nightly on record to bound it"
286
+ fi
287
+ gh label create trunk-red -R "$REPO" --color B60205 --description "Trunk fails a check" 2>/dev/null || true
288
+ body="$(printf 'The heavy lane failed on trunk at `%s`: %s\n\nCould have caused it: %s.\n\nA nightly never blocks a merge. Close this issue once a nightly is green again.\n' "$SHA" "$RUN_URL" "$range")"
289
+ gh issue create -R "$REPO" --title "$title" --label trunk-red --body "$body"