@futurelastic/colab-handbook 1.14.0-rc.8 → 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.
- package/README.md +19 -0
- package/README.vi.md +19 -0
- package/audit/audit.mjs +77 -16
- package/package.json +1 -1
- package/templates/README.md +64 -2
- package/templates/ci-laravel-heavy.yml +370 -0
- package/templates/ci-laravel.yml +27 -218
- package/templates/ci-node-heavy.yml +293 -0
- package/templates/ci-node.yml +23 -202
- package/templates/ci-python-heavy.yml +302 -0
- package/templates/ci-python.yml +26 -207
- package/templates/release-auto.yml +70 -1
- package/templates/release-tag.yml +20 -3
- package/tools/colab +475 -38
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/disposition.js +27 -10
- package/tools/lib/docs-only.js +76 -21
- package/tools/lib/git.js +6 -1
- package/tools/lib/instruction-file.js +26 -0
- package/tools/lib/instruction-gate.js +31 -2
- package/tools/lib/integration-profile.js +161 -0
- package/tools/lib/release-cut.js +10 -0
- package/tools/lib/release-finalize.js +9 -2
- package/tools/lib/secret-scan.js +132 -0
- package/tools/lib/ship-batch.js +71 -2
- package/tools/lib/stamp.js +16 -1
package/templates/ci-laravel.yml
CHANGED
|
@@ -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
|
-
#
|
|
34
|
-
#
|
|
35
|
-
#
|
|
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
|
|
127
|
-
#
|
|
128
|
-
#
|
|
129
|
-
#
|
|
130
|
-
#
|
|
131
|
-
#
|
|
132
|
-
#
|
|
133
|
-
#
|
|
134
|
-
#
|
|
135
|
-
#
|
|
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.
|
|
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,293 @@
|
|
|
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
|
+
# - Per INTEGRATION PROFILE (project.yml `integration-profile:`, #610): `gated` — colab ship
|
|
18
|
+
# dispatches this file at each landing and lands only on its green (keep workflow_dispatch and
|
|
19
|
+
# its `ref` input); `qualify` — make the cron below a clock, every few hours; `promote` —
|
|
20
|
+
# dispatch it on trunk's tip before colab promote. Absent = release-heavy: as copied.
|
|
21
|
+
# Heavy is opt-in per test; an unmarked test is light. The marker:
|
|
22
|
+
# a `test:heavy` script in package.json (e.g. over `*.heavy.test.*` files). `npm test`
|
|
23
|
+
# stays light; this lane runs both.
|
|
24
|
+
#
|
|
25
|
+
# Deliberately NOT triggered by push or pull_request: a run of this workflow must never count as
|
|
26
|
+
# a merge verdict (tools/lib/verify-runs.js sets schedule and dispatch runs aside).
|
|
27
|
+
# No concurrency block: a heavy run is never cancelled — a release may be waiting on it.
|
|
28
|
+
|
|
29
|
+
name: CI (heavy)
|
|
30
|
+
|
|
31
|
+
on:
|
|
32
|
+
schedule:
|
|
33
|
+
- cron: "23 2 * * *" # EDIT: nightly, UTC. Keep the cron in this one place.
|
|
34
|
+
workflow_dispatch:
|
|
35
|
+
inputs:
|
|
36
|
+
ref:
|
|
37
|
+
description: "Branch, tag or sha to test (empty = trunk's tip)"
|
|
38
|
+
required: false
|
|
39
|
+
default: ""
|
|
40
|
+
workflow_call:
|
|
41
|
+
inputs:
|
|
42
|
+
ref:
|
|
43
|
+
description: "Branch, tag or sha to test"
|
|
44
|
+
type: string
|
|
45
|
+
required: true
|
|
46
|
+
|
|
47
|
+
permissions: {}
|
|
48
|
+
|
|
49
|
+
env:
|
|
50
|
+
# EDIT: this repo's trunk (`trunk:` in .github/project.yml). A schedule always starts on the
|
|
51
|
+
# default branch; the nightly tests THIS branch's tip.
|
|
52
|
+
TRUNK: main
|
|
53
|
+
|
|
54
|
+
jobs:
|
|
55
|
+
# Resolves the one commit this run tests, and decides whether to test it. This job is the one
|
|
56
|
+
# that concludes `success` when the nightly skips: a run whose jobs all skip reads as not-green.
|
|
57
|
+
plan:
|
|
58
|
+
name: What to test
|
|
59
|
+
runs-on: ubuntu-latest # EDIT: needs `gh` (GitHub-hosted images have it).
|
|
60
|
+
timeout-minutes: 5
|
|
61
|
+
permissions:
|
|
62
|
+
actions: read
|
|
63
|
+
contents: read
|
|
64
|
+
outputs:
|
|
65
|
+
sha: ${{ steps.plan.outputs.sha }}
|
|
66
|
+
run: ${{ steps.plan.outputs.run }}
|
|
67
|
+
since: ${{ steps.plan.outputs.since }}
|
|
68
|
+
steps:
|
|
69
|
+
- name: Resolve the commit; skip a nightly on an unmoved trunk
|
|
70
|
+
id: plan
|
|
71
|
+
env:
|
|
72
|
+
GH_TOKEN: ${{ github.token }}
|
|
73
|
+
EVENT: ${{ github.event_name }}
|
|
74
|
+
REF: ${{ inputs.ref }}
|
|
75
|
+
REPO: ${{ github.repository }}
|
|
76
|
+
WORKFLOW_REF: ${{ github.workflow_ref }}
|
|
77
|
+
run: |
|
|
78
|
+
set -uo pipefail
|
|
79
|
+
target="${REF:-$TRUNK}"
|
|
80
|
+
if ! sha="$(gh api "repos/$REPO/commits/$target" --jq .sha)" || [ -z "$sha" ]; then
|
|
81
|
+
echo "::error::cannot resolve '$target' to a commit"
|
|
82
|
+
exit 1
|
|
83
|
+
fi
|
|
84
|
+
echo "sha=$sha" >> "$GITHUB_OUTPUT"
|
|
85
|
+
run=true; since=""
|
|
86
|
+
if [ "$EVENT" = "schedule" ]; then
|
|
87
|
+
# The last green nightly's tested commit, read from its `Full suite @ <sha>` job.
|
|
88
|
+
# Any read error leaves `since` empty, and the suite runs.
|
|
89
|
+
wf="${WORKFLOW_REF%@*}"; wf="${wf##*/}"
|
|
90
|
+
for id in $(gh api "repos/$REPO/actions/workflows/$wf/runs?event=schedule&status=success&per_page=10" \
|
|
91
|
+
--jq '.workflow_runs[].id' 2>/dev/null); do
|
|
92
|
+
since="$(gh api "repos/$REPO/actions/runs/$id/jobs" \
|
|
93
|
+
--jq '[.jobs[] | select(.conclusion == "success" and (.name | startswith("Full suite @ "))) | .name | ltrimstr("Full suite @ ")][0] // ""' 2>/dev/null || true)"
|
|
94
|
+
[ -z "$since" ] || break
|
|
95
|
+
done
|
|
96
|
+
if [ "$since" = "$sha" ]; then
|
|
97
|
+
run=false
|
|
98
|
+
echo "::notice title=heavy-skipped::$TRUNK has not moved since the last green nightly ($sha)"
|
|
99
|
+
fi
|
|
100
|
+
fi
|
|
101
|
+
echo "run=$run" >> "$GITHUB_OUTPUT"
|
|
102
|
+
echo "since=$since" >> "$GITHUB_OUTPUT"
|
|
103
|
+
echo "Heavy lane: ${run} at \`$sha\`${since:+ (last green nightly: \`$since\`)}" >> "$GITHUB_STEP_SUMMARY"
|
|
104
|
+
|
|
105
|
+
heavy:
|
|
106
|
+
# The tested sha is in the job name: the next nightly reads it back to decide whether trunk moved.
|
|
107
|
+
name: Full suite @ ${{ needs.plan.outputs.sha }}
|
|
108
|
+
needs: plan
|
|
109
|
+
if: ${{ needs.plan.outputs.run == 'true' }}
|
|
110
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
111
|
+
timeout-minutes: 120 # EDIT: well above YOUR heavy p99; the default is 360.
|
|
112
|
+
permissions:
|
|
113
|
+
contents: read
|
|
114
|
+
defaults:
|
|
115
|
+
run:
|
|
116
|
+
# EDIT: the same directory as ci.yml's build job.
|
|
117
|
+
working-directory: .
|
|
118
|
+
steps:
|
|
119
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
120
|
+
with:
|
|
121
|
+
ref: ${{ needs.plan.outputs.sha }}
|
|
122
|
+
persist-credentials: false
|
|
123
|
+
|
|
124
|
+
# Toolchain and install: the same steps as ci.yml's build job, so both lanes resolve the
|
|
125
|
+
# same versions. Keep them in step when you edit either.
|
|
126
|
+
# ---------------------------------------------------------------------------
|
|
127
|
+
# Toolchain resolution. Precedence, highest first:
|
|
128
|
+
# 1. .github/project.yml -> node: <version>
|
|
129
|
+
# 2. .nvmrc, else package.json -> engines.node
|
|
130
|
+
# 3. FAIL.
|
|
131
|
+
#
|
|
132
|
+
# There is deliberately NO fallback default. A silent default is exactly how a
|
|
133
|
+
# repo here ended up building on Node 20 in CI while deploying on Node 22 —
|
|
134
|
+
# CI was green and proved nothing about what actually shipped. If the version
|
|
135
|
+
# is not declared anywhere, that is a bug in the repo, and the build says so.
|
|
136
|
+
# ---------------------------------------------------------------------------
|
|
137
|
+
- name: Resolve Node version
|
|
138
|
+
id: toolchain
|
|
139
|
+
if: hashFiles('package.json') != ''
|
|
140
|
+
run: |
|
|
141
|
+
set -euo pipefail
|
|
142
|
+
|
|
143
|
+
# Normalise "^22", ">=22.1", "v22", "22.x" -> "22.1" / "22". setup-node
|
|
144
|
+
# accepts a partial version and picks the newest matching release.
|
|
145
|
+
normalise() {
|
|
146
|
+
printf '%s' "$1" \
|
|
147
|
+
| tr -d '"' \
|
|
148
|
+
| sed -E 's/^[^0-9]*//' \
|
|
149
|
+
| sed -E 's/[[:space:]].*$//' \
|
|
150
|
+
| sed -E 's/\.x$//' \
|
|
151
|
+
| sed -E 's/[^0-9.].*$//' \
|
|
152
|
+
| sed -E 's/\.$//'
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
NODE_VERSION=""
|
|
156
|
+
SOURCE=""
|
|
157
|
+
|
|
158
|
+
# 1. project.yml wins. Flat `node: 22` mapping; good enough, this file is
|
|
159
|
+
# a handful of keys by design.
|
|
160
|
+
if [ -f .github/project.yml ]; then
|
|
161
|
+
V="$(sed -nE 's/^[[:space:]]*node:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml | head -1 || true)"
|
|
162
|
+
if [ -n "$V" ] && [ "$V" != "null" ]; then
|
|
163
|
+
NODE_VERSION="$(normalise "$V")"; SOURCE=".github/project.yml (node:)"
|
|
164
|
+
fi
|
|
165
|
+
fi
|
|
166
|
+
|
|
167
|
+
# 2a. .nvmrc
|
|
168
|
+
if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
|
|
169
|
+
V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
|
|
170
|
+
if [ -n "$V" ]; then
|
|
171
|
+
NODE_VERSION="$(normalise "$V")"; SOURCE=".nvmrc"
|
|
172
|
+
fi
|
|
173
|
+
fi
|
|
174
|
+
|
|
175
|
+
# 2b. package.json -> engines.node
|
|
176
|
+
if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
|
|
177
|
+
V=""
|
|
178
|
+
if command -v node >/dev/null 2>&1; then
|
|
179
|
+
V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
|
|
180
|
+
elif command -v python3 >/dev/null 2>&1; then
|
|
181
|
+
V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
|
|
182
|
+
fi
|
|
183
|
+
if [ -n "$V" ]; then
|
|
184
|
+
NODE_VERSION="$(normalise "$V")"; SOURCE="package.json (engines.node)"
|
|
185
|
+
fi
|
|
186
|
+
fi
|
|
187
|
+
|
|
188
|
+
# 3. No declared source -> stop. Do not guess.
|
|
189
|
+
if [ -z "$NODE_VERSION" ]; then
|
|
190
|
+
echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
|
|
191
|
+
{
|
|
192
|
+
echo ""
|
|
193
|
+
echo "Declare it in ONE of these places (checked in this order):"
|
|
194
|
+
echo " 1. .github/project.yml -> node: \"22\" (preferred: one descriptor for the whole repo)"
|
|
195
|
+
echo " 2. .nvmrc -> 22 (also drives local dev via nvm/fnm)"
|
|
196
|
+
echo " or package.json -> \"engines\": { \"node\": \">=22\" }"
|
|
197
|
+
echo ""
|
|
198
|
+
echo "Pick the version your DEPLOY target runs. CI on a different major than"
|
|
199
|
+
echo "production proves nothing."
|
|
200
|
+
} >&2
|
|
201
|
+
exit 1
|
|
202
|
+
fi
|
|
203
|
+
|
|
204
|
+
echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
|
|
205
|
+
echo "Node $NODE_VERSION (resolved from: $SOURCE)"
|
|
206
|
+
echo "Node **$NODE_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
|
|
207
|
+
|
|
208
|
+
# Package cache (#571): on only on a GitHub-hosted runner AND with package-lock.json
|
|
209
|
+
# present. Both halves are load-bearing:
|
|
210
|
+
# - No lockfile → setup-node's `cache:` fails the step outright ("Dependencies lock
|
|
211
|
+
# file is not found"), and this template allows a repo without one.
|
|
212
|
+
# - Self-hosted → off. A persistent runner already keeps ~/.npm between jobs; a
|
|
213
|
+
# remote cache on top was measured as a loss, not a saving (#512).
|
|
214
|
+
# npm only: `cache: pnpm` needs pnpm on PATH before this step, and the install step
|
|
215
|
+
# below enables it through corepack afterwards. `package-manager-cache` is pinned to
|
|
216
|
+
# the same condition so setup-node's automatic `packageManager` caching cannot switch
|
|
217
|
+
# it back on where the condition says off.
|
|
218
|
+
# EDIT: self-hosted runners are already off; to turn caching off everywhere, replace
|
|
219
|
+
# both expressions with '' and false. If the app is not at the root, point the
|
|
220
|
+
# hashFiles() and a `cache-dependency-path:` at its package-lock.json.
|
|
221
|
+
- name: Setup Node
|
|
222
|
+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
|
|
223
|
+
if: hashFiles('package.json') != ''
|
|
224
|
+
with:
|
|
225
|
+
node-version: ${{ steps.toolchain.outputs.node-version }}
|
|
226
|
+
cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
|
|
227
|
+
package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
|
|
228
|
+
|
|
229
|
+
- name: Install dependencies
|
|
230
|
+
if: hashFiles('package.json') != ''
|
|
231
|
+
run: |
|
|
232
|
+
# Lockfile decides the package manager. `npm ci` / `--frozen-lockfile` are
|
|
233
|
+
# intentional: CI must fail on a stale lockfile rather than silently resolve
|
|
234
|
+
# a different dependency tree than the developer had.
|
|
235
|
+
if [ -f pnpm-lock.yaml ]; then
|
|
236
|
+
corepack enable
|
|
237
|
+
pnpm install --frozen-lockfile
|
|
238
|
+
elif [ -f package-lock.json ]; then
|
|
239
|
+
npm ci
|
|
240
|
+
else
|
|
241
|
+
echo "::warning::No lockfile found — falling back to 'npm install'. Commit a lockfile so CI is reproducible."
|
|
242
|
+
npm install
|
|
243
|
+
fi
|
|
244
|
+
|
|
245
|
+
- name: Test (the whole suite)
|
|
246
|
+
run: |
|
|
247
|
+
# `npm test` (light) and then `test:heavy`, if this repo has one.
|
|
248
|
+
has() { node -e "const s=(require('./package.json').scripts)||{};process.exit(s['$1']?0:1)" 2>/dev/null; }
|
|
249
|
+
if has test; then npm test; else echo "::notice::No 'test' script in package.json."; fi
|
|
250
|
+
if has test:heavy; then npm run test:heavy; else echo "::notice::No 'test:heavy' script — nothing is marked heavy."; fi
|
|
251
|
+
# EDIT: integration, browser/e2e or load jobs go here, or as jobs of their own with
|
|
252
|
+
# `needs: plan` and the same `if:` and checkout ref as this one.
|
|
253
|
+
|
|
254
|
+
# A red NIGHTLY is a trunk finding, never a merge block: one open issue per lane. An open issue
|
|
255
|
+
# with the same title suppresses a new one; an issue list that cannot be read files nothing and
|
|
256
|
+
# fails this job, so a silent miss is never mistaken for "already reported".
|
|
257
|
+
report:
|
|
258
|
+
name: Report a red nightly
|
|
259
|
+
needs: [plan, heavy]
|
|
260
|
+
if: ${{ always() && github.event_name == 'schedule' && needs.heavy.result == 'failure' }}
|
|
261
|
+
runs-on: ubuntu-latest # EDIT: needs `gh`.
|
|
262
|
+
timeout-minutes: 5
|
|
263
|
+
permissions:
|
|
264
|
+
issues: write
|
|
265
|
+
steps:
|
|
266
|
+
- name: File one trunk-red issue
|
|
267
|
+
env:
|
|
268
|
+
GH_TOKEN: ${{ github.token }}
|
|
269
|
+
REPO: ${{ github.repository }}
|
|
270
|
+
SHA: ${{ needs.plan.outputs.sha }}
|
|
271
|
+
SINCE: ${{ needs.plan.outputs.since }}
|
|
272
|
+
WORKFLOW: ${{ github.workflow }}
|
|
273
|
+
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
|
274
|
+
run: |
|
|
275
|
+
set -uo pipefail
|
|
276
|
+
title="Nightly heavy lane red: $WORKFLOW"
|
|
277
|
+
if ! open="$(gh issue list -R "$REPO" --state open --search "\"$title\" in:title" --json number,title \
|
|
278
|
+
--jq "[.[] | select(.title == \"$title\")][0].number // \"\"")"; then
|
|
279
|
+
echo "::error::cannot read this repo's issues — nothing filed; the red run is the only report"
|
|
280
|
+
exit 1
|
|
281
|
+
fi
|
|
282
|
+
if [ -n "$open" ]; then
|
|
283
|
+
echo "::notice::#$open already reports this lane red — not filing another."
|
|
284
|
+
exit 0
|
|
285
|
+
fi
|
|
286
|
+
if [ -n "$SINCE" ]; then
|
|
287
|
+
range="[\`${SINCE:0:12}..${SHA:0:12}\`]($GITHUB_SERVER_URL/$REPO/compare/$SINCE...$SHA) — the commits since the last green nightly"
|
|
288
|
+
else
|
|
289
|
+
range="up to \`${SHA:0:12}\` — no green nightly on record to bound it"
|
|
290
|
+
fi
|
|
291
|
+
gh label create trunk-red -R "$REPO" --color B60205 --description "Trunk fails a check" 2>/dev/null || true
|
|
292
|
+
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")"
|
|
293
|
+
gh issue create -R "$REPO" --title "$title" --label trunk-red --body "$body"
|