@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.
- package/README.md +19 -0
- package/README.vi.md +19 -0
- package/audit/audit.mjs +59 -15
- 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 +463 -38
- 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/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-node.yml
CHANGED
|
@@ -22,6 +22,13 @@
|
|
|
22
22
|
# repo without them is not forced to add placeholders to keep CI green.
|
|
23
23
|
# 5. Build, if package.json declares the BUILD_COMMAND script.
|
|
24
24
|
# 6. Opt-in, commented: a Migration round-trip for `migration-grant: reviewer` (#494).
|
|
25
|
+
#
|
|
26
|
+
# LIGHT LANE (#607): this file runs on every push and is what `colab ship` reads. Keep it
|
|
27
|
+
# fast — secret scan, build, typecheck/lint, the fast tests (target: under 5 minutes).
|
|
28
|
+
# The full suite, integration, e2e and load tests belong in the HEAVY lane,
|
|
29
|
+
# templates/ci-node-heavy.yml copied to .github/workflows/ci-heavy.yml: it runs nightly
|
|
30
|
+
# and on every release candidate/tag, never per merge. Tests are light unless marked heavy:
|
|
31
|
+
# a `test:heavy` script in package.json (e.g. over `*.heavy.test.*` files) that `test` does not run.
|
|
25
32
|
|
|
26
33
|
name: CI
|
|
27
34
|
|
|
@@ -42,6 +49,10 @@ on:
|
|
|
42
49
|
# dev is the trunk, so a main-only trigger runs zero checks on the branch you
|
|
43
50
|
# merge into, and nothing looks broken (CONVENTIONS.md §7).
|
|
44
51
|
branches: ['**']
|
|
52
|
+
# Optional (#607): skip documentation-only pushes here, if you like. `colab ship` decides a
|
|
53
|
+
# docs-only change from the diff and lands it without waiting for CI (CONVENTIONS.md §4,
|
|
54
|
+
# "Docs-only — no CI wait"), so a docs push with no run does not hold a merge.
|
|
55
|
+
# paths-ignore: ['**/*.md', 'docs/**']
|
|
45
56
|
# No `pull_request:` here (#512). A branch with an open PR in this repository already
|
|
46
57
|
# has a push run at the same head, and a `pull_request` run beside it doubled the CI
|
|
47
58
|
# per commit while testing a merge ref instead of the sha that lands. Readers keep only
|
|
@@ -88,53 +99,16 @@ env:
|
|
|
88
99
|
# jobs from different runs interleave, and trunk can wait behind branch runs.
|
|
89
100
|
# Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
|
|
90
101
|
jobs:
|
|
91
|
-
# Already tested
|
|
92
|
-
#
|
|
93
|
-
#
|
|
94
|
-
#
|
|
95
|
-
#
|
|
96
|
-
#
|
|
97
|
-
#
|
|
98
|
-
#
|
|
99
|
-
#
|
|
100
|
-
#
|
|
101
|
-
# before (fail-open: this job never fails the run). Every later push has
|
|
102
|
-
# `created == false`, so a real commit always gets the full suite, with no extra hop.
|
|
103
|
-
# Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
|
|
104
|
-
# skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
|
|
105
|
-
# §4, "Branch CI"). This job is the one that ends green.
|
|
106
|
-
#
|
|
107
|
-
# Already tested at this TREE? (#493) — the squash merge.
|
|
108
|
-
# A ship squash-merges a branch whose green run already contained the current base, so
|
|
109
|
-
# the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
|
|
110
|
-
# sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
|
|
111
|
-
# workflow have a green `push` run, on another ref of this repo, whose commit has THIS
|
|
112
|
-
# exact tree? It confirms the tree through the git object, never only the run listing.
|
|
113
|
-
# Yes → the suite is skipped and the run cites the run it relied on (a
|
|
114
|
-
# `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
|
|
115
|
-
# trees cover every committed byte, workflows and lockfiles included — NOT runner images,
|
|
116
|
-
# unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
|
|
117
|
-
# depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
|
|
118
|
-
# descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
|
|
119
|
-
# any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
|
|
120
|
-
# A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
|
|
121
|
-
# asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
|
|
122
|
-
# A cited run is reused only if it skipped no job but this one: a job gated on the trunk
|
|
123
|
-
# ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
|
|
124
|
-
# (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
|
|
125
|
-
#
|
|
126
|
-
# Only documentation changed? (#570) — opt-in, `ci-docs-skip:` in .github/project.yml.
|
|
127
|
-
# When the two modes above find nothing, a repo that declared `ci-docs-skip` at THIS sha
|
|
128
|
-
# asks a third question: is every path changed since the base documentation, by the rule
|
|
129
|
-
# `colab ship` applies (CONVENTIONS.md §2, the docs-only exception: .md/.mdx/.txt or under
|
|
130
|
-
# docs/, never agent rules, config, a build input like requirements*.txt, a symlink, a
|
|
131
|
-
# submodule or a binary), and does the base
|
|
132
|
-
# have a green run of this workflow? The base is the merge base with trunk on a ref-creating
|
|
133
|
-
# push, and the previous tip on a push to trunk. Yes → the suite is skipped and the run
|
|
134
|
-
# leaves a `docs-only-skip` notice naming the base and its green run. A path the suite reads
|
|
135
|
-
# (docs/api/ feeding a generator) is listed in `ci-docs-skip` and always runs the suite. Any
|
|
136
|
-
# doubt (no opt-in, a red or unrun base, an API or fetch failure) runs the full suite. A run
|
|
137
|
-
# skipped this way is never cited as tree-reuse proof: it skipped every job (#511).
|
|
102
|
+
# Already tested? This job is the one that concludes `success` when the suite is skipped: a
|
|
103
|
+
# run whose jobs ALL skip concludes `skipped`, which `colab ship` reads as not-green.
|
|
104
|
+
# - At this SHA (#418): on a ref's first push (a claim push), a green non-PR run of this
|
|
105
|
+
# workflow at the same sha means the suite already ran.
|
|
106
|
+
# - At this TREE (#493): on a push to trunk, a green push run elsewhere whose commit has the
|
|
107
|
+
# byte-identical tree (a squash of a branch that already contained its base) is reused and
|
|
108
|
+
# cited in a `tree-already-green` notice. `tree-reuse: off` in .github/project.yml opts out.
|
|
109
|
+
# A run that skipped a job (a trunk-only job skips on branches) is never reused (#511), so
|
|
110
|
+
# never put a trunk-only job (publish, deploy, release) behind this gate.
|
|
111
|
+
# Any doubt — no run, red, an API error — runs the full suite; this job never fails the run.
|
|
138
112
|
dedupe:
|
|
139
113
|
name: Already tested at this sha or tree?
|
|
140
114
|
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
@@ -145,7 +119,7 @@ jobs:
|
|
|
145
119
|
actions: read
|
|
146
120
|
contents: read
|
|
147
121
|
outputs:
|
|
148
|
-
tested: ${{ steps.
|
|
122
|
+
tested: ${{ steps.check.outputs.tested }}
|
|
149
123
|
cited: ${{ steps.check.outputs.cited }}
|
|
150
124
|
steps:
|
|
151
125
|
- name: Look for a green run of this workflow at this sha or tree
|
|
@@ -248,160 +222,6 @@ jobs:
|
|
|
248
222
|
fi
|
|
249
223
|
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
250
224
|
[ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
|
|
251
|
-
# Docs-only (#570) — the two steps below run only when the step above found nothing.
|
|
252
|
-
- name: Find the base a docs-only change would rely on
|
|
253
|
-
id: docs_base
|
|
254
|
-
if: steps.check.outputs.tested != 'true'
|
|
255
|
-
env:
|
|
256
|
-
GH_TOKEN: ${{ github.token }}
|
|
257
|
-
REPO: ${{ github.repository }}
|
|
258
|
-
RUN_ID: ${{ github.run_id }}
|
|
259
|
-
SHA: ${{ github.sha }}
|
|
260
|
-
BEFORE: ${{ github.event.before }}
|
|
261
|
-
CREATED: ${{ github.event.created }}
|
|
262
|
-
REF: ${{ github.ref }}
|
|
263
|
-
REF_NAME: ${{ github.ref_name }}
|
|
264
|
-
run: |
|
|
265
|
-
base=
|
|
266
|
-
# The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
|
|
267
|
-
# doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
|
|
268
|
-
optin() {
|
|
269
|
-
local v items
|
|
270
|
-
v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
|
|
271
|
-
if [ -z "$v" ]; then
|
|
272
|
-
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}')"
|
|
273
|
-
[ -n "$items" ] || return 1
|
|
274
|
-
elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
|
|
275
|
-
v="${v#[}"; v="${v%]}"
|
|
276
|
-
items="$(printf '%s' "$v" | tr ',' '\n')"
|
|
277
|
-
else
|
|
278
|
-
return 1
|
|
279
|
-
fi
|
|
280
|
-
EXCLUDE=
|
|
281
|
-
while IFS= read -r it; do
|
|
282
|
-
it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
|
|
283
|
-
[ -n "$it" ] || continue
|
|
284
|
-
case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
|
|
285
|
-
printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
|
|
286
|
-
EXCLUDE="$EXCLUDE ${it%/}"
|
|
287
|
-
done <<< "$items"
|
|
288
|
-
}
|
|
289
|
-
if ! command -v gh >/dev/null 2>&1; then
|
|
290
|
-
echo "gh is not installed on this runner — docs-only mode is off (#570)."
|
|
291
|
-
elif [ "${REF#refs/heads/}" = "$REF" ]; then
|
|
292
|
-
echo "$REF is not a branch — docs-only mode is off (#570)."
|
|
293
|
-
elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
|
|
294
|
-
echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
|
|
295
|
-
elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
|
|
296
|
-
echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
|
|
297
|
-
elif ! optin; then
|
|
298
|
-
echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
|
|
299
|
-
else
|
|
300
|
-
TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
|
|
301
|
-
if [ -z "$TRUNK" ]; then
|
|
302
|
-
echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
|
|
303
|
-
elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
|
|
304
|
-
# A new branch: the change is everything since it left trunk (the diff the squash lands).
|
|
305
|
-
base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
|
|
306
|
-
[ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
|
|
307
|
-
elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
|
|
308
|
-
base="$BEFORE" # a push to trunk: the change is what this push added
|
|
309
|
-
else
|
|
310
|
-
echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
|
|
311
|
-
fi
|
|
312
|
-
# The base must itself be green: a docs-only change cannot make a red suite green. The base
|
|
313
|
-
# is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
|
|
314
|
-
# branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
|
|
315
|
-
# skipped on the branch, #511). Still running, red, or none: the full suite.
|
|
316
|
-
if [ -n "$base" ]; then
|
|
317
|
-
if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
|
|
318
|
-
|| ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
|
|
319
|
-
--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
|
|
320
|
-
echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
|
|
321
|
-
base=
|
|
322
|
-
elif [ -z "$URL" ]; then
|
|
323
|
-
echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
|
|
324
|
-
base=
|
|
325
|
-
fi
|
|
326
|
-
fi
|
|
327
|
-
fi
|
|
328
|
-
if [ -n "$base" ]; then
|
|
329
|
-
echo "base=$base" >> "$GITHUB_OUTPUT"
|
|
330
|
-
echo "base_run=$URL" >> "$GITHUB_OUTPUT"
|
|
331
|
-
echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
|
|
332
|
-
fi
|
|
333
|
-
- name: Is every changed path documentation?
|
|
334
|
-
id: docs
|
|
335
|
-
if: steps.docs_base.outputs.base != ''
|
|
336
|
-
env:
|
|
337
|
-
GH_TOKEN: ${{ github.token }}
|
|
338
|
-
SERVER_URL: ${{ github.server_url }}
|
|
339
|
-
REPO: ${{ github.repository }}
|
|
340
|
-
SHA: ${{ github.sha }}
|
|
341
|
-
BASE: ${{ steps.docs_base.outputs.base }}
|
|
342
|
-
BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
|
|
343
|
-
EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
|
|
344
|
-
run: |
|
|
345
|
-
tested=false
|
|
346
|
-
# Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
|
|
347
|
-
# §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
|
|
348
|
-
# Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
|
|
349
|
-
reason() {
|
|
350
|
-
local p="$1" base dir x
|
|
351
|
-
base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
|
|
352
|
-
case "$p" in \"*) echo "quoted path"; return ;; esac
|
|
353
|
-
for x in $EXCLUDE; do
|
|
354
|
-
case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
|
|
355
|
-
done
|
|
356
|
-
case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
|
|
357
|
-
# A build input despite the extension: the cure rule's Python manifest (any case), a pip
|
|
358
|
-
# constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
|
|
359
|
-
lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
|
|
360
|
-
case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
|
|
361
|
-
case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
|
|
362
|
-
[ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
|
|
363
|
-
case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
|
|
364
|
-
case "$p" in docs/*) return ;; esac
|
|
365
|
-
case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
|
|
366
|
-
echo "not .md/.mdx/.txt and not under docs/"
|
|
367
|
-
}
|
|
368
|
-
# Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
|
|
369
|
-
G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
|
|
370
|
-
AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
|
|
371
|
-
if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
|
|
372
|
-
&& git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
|
|
373
|
-
&& git -C "$G" config http.extraheader "$AUTH" \
|
|
374
|
-
&& git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
|
|
375
|
-
echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
|
|
376
|
-
elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
|
|
377
|
-
|| ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
|
|
378
|
-
echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
|
|
379
|
-
elif [ -z "$RAW" ]; then
|
|
380
|
-
echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
|
|
381
|
-
else
|
|
382
|
-
bad=; n=0
|
|
383
|
-
while IFS= read -r line; do
|
|
384
|
-
meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
|
|
385
|
-
why="$(reason "$p")"
|
|
386
|
-
set -- $meta
|
|
387
|
-
case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
|
|
388
|
-
case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
|
|
389
|
-
[ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
|
|
390
|
-
done <<< "$RAW"
|
|
391
|
-
while IFS=$'\t' read -r a d p; do
|
|
392
|
-
if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
|
|
393
|
-
done <<< "$NUM"
|
|
394
|
-
if [ -n "$bad" ]; then
|
|
395
|
-
echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
|
|
396
|
-
else
|
|
397
|
-
tested=true
|
|
398
|
-
echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
|
|
399
|
-
echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
|
|
400
|
-
echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
|
|
401
|
-
fi
|
|
402
|
-
fi
|
|
403
|
-
rm -rf "$G"
|
|
404
|
-
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
405
225
|
|
|
406
226
|
gitleaks:
|
|
407
227
|
name: Secret scan (gitleaks)
|
|
@@ -761,6 +581,7 @@ jobs:
|
|
|
761
581
|
# `maxWorkers: process.env.CI ? 4 : undefined`, jest `--maxWorkers=4`,
|
|
762
582
|
# node:test `--test-concurrency=4`. GitHub Actions sets CI=true. Why and how
|
|
763
583
|
# to size it: CONVENTIONS.md §7, "Self-hosted runners".
|
|
584
|
+
# Light lane: `npm test` only. Heavy tests live in a `test:heavy` script, run by ci-heavy.yml.
|
|
764
585
|
- name: Test
|
|
765
586
|
if: steps.scripts.outputs.test == 'true'
|
|
766
587
|
run: npm test
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
# CI heavy lane (Python) — TEMPLATE. Copy me into your repo at .github/workflows/ci-heavy.yml,
|
|
2
|
+
# beside ci.yml (copied from ci-python.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
|
+
# the pytest marker `heavy` (`@pytest.mark.heavy`, registered in pytest.ini or
|
|
23
|
+
# pyproject.toml). The light lane deselects it; this lane runs everything.
|
|
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
|
+
# EDIT: the same value as ci.yml.
|
|
54
|
+
PACKAGE_DIR: "."
|
|
55
|
+
|
|
56
|
+
jobs:
|
|
57
|
+
# Resolves the one commit this run tests, and decides whether to test it. This job is the one
|
|
58
|
+
# that concludes `success` when the nightly skips: a run whose jobs all skip reads as not-green.
|
|
59
|
+
plan:
|
|
60
|
+
name: What to test
|
|
61
|
+
runs-on: ubuntu-latest # EDIT: needs `gh` (GitHub-hosted images have it).
|
|
62
|
+
timeout-minutes: 5
|
|
63
|
+
permissions:
|
|
64
|
+
actions: read
|
|
65
|
+
contents: read
|
|
66
|
+
outputs:
|
|
67
|
+
sha: ${{ steps.plan.outputs.sha }}
|
|
68
|
+
run: ${{ steps.plan.outputs.run }}
|
|
69
|
+
since: ${{ steps.plan.outputs.since }}
|
|
70
|
+
steps:
|
|
71
|
+
- name: Resolve the commit; skip a nightly on an unmoved trunk
|
|
72
|
+
id: plan
|
|
73
|
+
env:
|
|
74
|
+
GH_TOKEN: ${{ github.token }}
|
|
75
|
+
EVENT: ${{ github.event_name }}
|
|
76
|
+
REF: ${{ inputs.ref }}
|
|
77
|
+
REPO: ${{ github.repository }}
|
|
78
|
+
WORKFLOW_REF: ${{ github.workflow_ref }}
|
|
79
|
+
run: |
|
|
80
|
+
set -uo pipefail
|
|
81
|
+
target="${REF:-$TRUNK}"
|
|
82
|
+
if ! sha="$(gh api "repos/$REPO/commits/$target" --jq .sha)" || [ -z "$sha" ]; then
|
|
83
|
+
echo "::error::cannot resolve '$target' to a commit"
|
|
84
|
+
exit 1
|
|
85
|
+
fi
|
|
86
|
+
echo "sha=$sha" >> "$GITHUB_OUTPUT"
|
|
87
|
+
run=true; since=""
|
|
88
|
+
if [ "$EVENT" = "schedule" ]; then
|
|
89
|
+
# The last green nightly's tested commit, read from its `Full suite @ <sha>` job.
|
|
90
|
+
# Any read error leaves `since` empty, and the suite runs.
|
|
91
|
+
wf="${WORKFLOW_REF%@*}"; wf="${wf##*/}"
|
|
92
|
+
for id in $(gh api "repos/$REPO/actions/workflows/$wf/runs?event=schedule&status=success&per_page=10" \
|
|
93
|
+
--jq '.workflow_runs[].id' 2>/dev/null); do
|
|
94
|
+
since="$(gh api "repos/$REPO/actions/runs/$id/jobs" \
|
|
95
|
+
--jq '[.jobs[] | select(.conclusion == "success" and (.name | startswith("Full suite @ "))) | .name | ltrimstr("Full suite @ ")][0] // ""' 2>/dev/null || true)"
|
|
96
|
+
[ -z "$since" ] || break
|
|
97
|
+
done
|
|
98
|
+
if [ "$since" = "$sha" ]; then
|
|
99
|
+
run=false
|
|
100
|
+
echo "::notice title=heavy-skipped::$TRUNK has not moved since the last green nightly ($sha)"
|
|
101
|
+
fi
|
|
102
|
+
fi
|
|
103
|
+
echo "run=$run" >> "$GITHUB_OUTPUT"
|
|
104
|
+
echo "since=$since" >> "$GITHUB_OUTPUT"
|
|
105
|
+
echo "Heavy lane: ${run} at \`$sha\`${since:+ (last green nightly: \`$since\`)}" >> "$GITHUB_STEP_SUMMARY"
|
|
106
|
+
|
|
107
|
+
heavy:
|
|
108
|
+
# The tested sha is in the job name: the next nightly reads it back to decide whether trunk moved.
|
|
109
|
+
name: Full suite @ ${{ needs.plan.outputs.sha }}
|
|
110
|
+
needs: plan
|
|
111
|
+
if: ${{ needs.plan.outputs.run == 'true' }}
|
|
112
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
113
|
+
timeout-minutes: 120 # EDIT: well above YOUR heavy p99; the default is 360.
|
|
114
|
+
permissions:
|
|
115
|
+
contents: read
|
|
116
|
+
defaults:
|
|
117
|
+
run:
|
|
118
|
+
# EDIT: the same directory as ci.yml's build job.
|
|
119
|
+
working-directory: .
|
|
120
|
+
steps:
|
|
121
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
122
|
+
with:
|
|
123
|
+
ref: ${{ needs.plan.outputs.sha }}
|
|
124
|
+
persist-credentials: false
|
|
125
|
+
|
|
126
|
+
# Toolchain and install: the same steps as ci.yml's build job, so both lanes resolve the
|
|
127
|
+
# same versions. Keep them in step when you edit either.
|
|
128
|
+
# ---------------------------------------------------------------------------
|
|
129
|
+
# Toolchain resolution. Precedence, highest first:
|
|
130
|
+
# 1. .github/project.yml -> python: <version>
|
|
131
|
+
# 2. .python-version (pyenv; also what most local tooling reads)
|
|
132
|
+
# 3. pyproject.toml -> [project] requires-python
|
|
133
|
+
# 4. FAIL.
|
|
134
|
+
#
|
|
135
|
+
# NOTE what is NOT on that list: requirements.txt. It pins DEPENDENCIES, never
|
|
136
|
+
# the interpreter — a repo with only a requirements.txt has declared nothing
|
|
137
|
+
# about which Python it runs on, and this workflow will (correctly) stop and
|
|
138
|
+
# say so. Add `python:` to project.yml or a `.python-version`; do not paper
|
|
139
|
+
# over it with a hardcoded version here.
|
|
140
|
+
#
|
|
141
|
+
# There is deliberately NO fallback default. A silent default is exactly how a
|
|
142
|
+
# repo here ended up building on Node 20 in CI while deploying on Node 22 —
|
|
143
|
+
# CI was green and proved nothing about what actually shipped. Python has the
|
|
144
|
+
# same failure with sharper edges: a minor is a real feature release, so 3.12
|
|
145
|
+
# vs 3.13 is not a cosmetic difference.
|
|
146
|
+
# ---------------------------------------------------------------------------
|
|
147
|
+
- name: Resolve Python version
|
|
148
|
+
id: toolchain
|
|
149
|
+
run: |
|
|
150
|
+
set -euo pipefail
|
|
151
|
+
|
|
152
|
+
# ">=3.13" / "~=3.12" / "3.13.1" / "3.13" -> "3.13" / "3.12" / "3.13.1"
|
|
153
|
+
normalise() {
|
|
154
|
+
printf '%s' "$1" \
|
|
155
|
+
| tr -d '"' \
|
|
156
|
+
| sed -E 's/^[^0-9]*//' \
|
|
157
|
+
| sed -E 's/[[:space:],].*$//' \
|
|
158
|
+
| sed -E 's/\.(x|\*)$//' \
|
|
159
|
+
| sed -E 's/[^0-9.].*$//' \
|
|
160
|
+
| sed -E 's/\.$//'
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
PY_VERSION=""
|
|
164
|
+
SOURCE=""
|
|
165
|
+
|
|
166
|
+
# 1. project.yml wins. Flat `python: 3.13` mapping; good enough, this file
|
|
167
|
+
# is a handful of keys by design.
|
|
168
|
+
if [ -f .github/project.yml ]; then
|
|
169
|
+
V="$(sed -nE 's/^[[:space:]]*python:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml | head -1 || true)"
|
|
170
|
+
if [ -n "$V" ] && [ "$V" != "null" ]; then
|
|
171
|
+
PY_VERSION="$(normalise "$V")"; SOURCE=".github/project.yml (python:)"
|
|
172
|
+
fi
|
|
173
|
+
fi
|
|
174
|
+
|
|
175
|
+
# 2. .python-version
|
|
176
|
+
if [ -z "$PY_VERSION" ] && [ -f .python-version ]; then
|
|
177
|
+
V="$(grep -vE '^[[:space:]]*(#|$)' .python-version | head -1 | tr -d '[:space:]' || true)"
|
|
178
|
+
if [ -n "$V" ]; then
|
|
179
|
+
PY_VERSION="$(normalise "$V")"; SOURCE=".python-version"
|
|
180
|
+
fi
|
|
181
|
+
fi
|
|
182
|
+
|
|
183
|
+
# 3. pyproject.toml -> [project] requires-python. Read with a line match, not
|
|
184
|
+
# a TOML parser: the field is a single top-level string and the runner is
|
|
185
|
+
# not guaranteed to have tomllib available before setup-python has run.
|
|
186
|
+
if [ -z "$PY_VERSION" ] && [ -f pyproject.toml ]; then
|
|
187
|
+
V="$(sed -nE 's/^[[:space:]]*requires-python[[:space:]]*=[[:space:]]*["'"'"']([^"'"'"']+)["'"'"'].*/\1/p' pyproject.toml | head -1 || true)"
|
|
188
|
+
if [ -n "$V" ]; then
|
|
189
|
+
PY_VERSION="$(normalise "$V")"; SOURCE="pyproject.toml (requires-python)"
|
|
190
|
+
fi
|
|
191
|
+
fi
|
|
192
|
+
|
|
193
|
+
# 4. No declared source -> stop. Do not guess.
|
|
194
|
+
if [ -z "$PY_VERSION" ]; then
|
|
195
|
+
echo "::error::No Python version is declared in this repository, and this workflow refuses to guess one."
|
|
196
|
+
{
|
|
197
|
+
echo ""
|
|
198
|
+
echo "Declare it in ONE of these places (checked in this order):"
|
|
199
|
+
echo " 1. .github/project.yml -> python: \"3.13\" (preferred: one descriptor for the whole repo)"
|
|
200
|
+
echo " 2. .python-version -> 3.13 (also drives local dev via pyenv)"
|
|
201
|
+
echo " 3. pyproject.toml -> [project] requires-python = \">=3.13\""
|
|
202
|
+
echo ""
|
|
203
|
+
echo "requirements.txt does NOT count — it pins dependencies, not the interpreter."
|
|
204
|
+
echo "Pick the version your DEPLOY target runs. CI on a different minor than"
|
|
205
|
+
echo "production proves less than you think."
|
|
206
|
+
} >&2
|
|
207
|
+
exit 1
|
|
208
|
+
fi
|
|
209
|
+
|
|
210
|
+
echo "python-version=$PY_VERSION" >> "$GITHUB_OUTPUT"
|
|
211
|
+
echo "Python $PY_VERSION (resolved from: $SOURCE)"
|
|
212
|
+
echo "Python **$PY_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
|
|
213
|
+
|
|
214
|
+
# Package cache (#571): pip's wheel cache, on only on a GitHub-hosted runner AND with a
|
|
215
|
+
# dependency manifest present. Both halves are load-bearing:
|
|
216
|
+
# - No requirements*.txt / pyproject.toml → setup-python's `cache: pip` fails the step
|
|
217
|
+
# ("No file ... matched"), and this template allows a repo with neither.
|
|
218
|
+
# - Self-hosted → off. A persistent runner already keeps ~/.cache/pip between jobs; a
|
|
219
|
+
# remote cache on top was measured as a loss, not a saving (#512).
|
|
220
|
+
# The cache holds downloaded wheels, never a resolution: it cannot change which versions
|
|
221
|
+
# install, so a repo without a pinned lockfile is no less reproducible with it on.
|
|
222
|
+
# EDIT: self-hosted runners are already off; to turn caching off everywhere, replace the
|
|
223
|
+
# `cache:` expression with ''. Manifests outside the root → widen cache-dependency-path
|
|
224
|
+
# and the hashFiles() to match.
|
|
225
|
+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
|
|
226
|
+
with:
|
|
227
|
+
python-version: ${{ steps.toolchain.outputs.python-version }}
|
|
228
|
+
cache: ${{ runner.environment == 'github-hosted' && hashFiles('requirements*.txt', 'pyproject.toml') != '' && 'pip' || '' }}
|
|
229
|
+
cache-dependency-path: |
|
|
230
|
+
requirements*.txt
|
|
231
|
+
pyproject.toml
|
|
232
|
+
|
|
233
|
+
- name: Install dependencies
|
|
234
|
+
run: |
|
|
235
|
+
python -m pip install --upgrade pip
|
|
236
|
+
# Whichever manifest the repo actually has. A packaged project (pyproject)
|
|
237
|
+
# installs itself so imports resolve the way they will in production;
|
|
238
|
+
# a plain requirements.txt service just installs its pins.
|
|
239
|
+
if [ -f pyproject.toml ]; then
|
|
240
|
+
pip install -e .
|
|
241
|
+
elif [ -f requirements.txt ]; then
|
|
242
|
+
pip install -r requirements.txt
|
|
243
|
+
else
|
|
244
|
+
echo "::warning::No pyproject.toml or requirements.txt — nothing to install."
|
|
245
|
+
fi
|
|
246
|
+
|
|
247
|
+
- name: Byte-compile
|
|
248
|
+
# The cheapest gate there is: every module parses. Catches the syntax error
|
|
249
|
+
# that only ever runs on a code path nobody tests.
|
|
250
|
+
run: python -m compileall -q "$PACKAGE_DIR"
|
|
251
|
+
|
|
252
|
+
- name: Test (the whole suite)
|
|
253
|
+
run: |
|
|
254
|
+
if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
|
|
255
|
+
if python -m pytest --version >/dev/null 2>&1; then
|
|
256
|
+
python -m pytest -q
|
|
257
|
+
else
|
|
258
|
+
echo "::notice::pytest not installed — nothing to run."
|
|
259
|
+
fi
|
|
260
|
+
# EDIT: integration, browser/e2e or load jobs go here, or as jobs of their own with
|
|
261
|
+
# `needs: plan` and the same `if:` and checkout ref as this one.
|
|
262
|
+
|
|
263
|
+
# A red NIGHTLY is a trunk finding, never a merge block: one open issue per lane. An open issue
|
|
264
|
+
# with the same title suppresses a new one; an issue list that cannot be read files nothing and
|
|
265
|
+
# fails this job, so a silent miss is never mistaken for "already reported".
|
|
266
|
+
report:
|
|
267
|
+
name: Report a red nightly
|
|
268
|
+
needs: [plan, heavy]
|
|
269
|
+
if: ${{ always() && github.event_name == 'schedule' && needs.heavy.result == 'failure' }}
|
|
270
|
+
runs-on: ubuntu-latest # EDIT: needs `gh`.
|
|
271
|
+
timeout-minutes: 5
|
|
272
|
+
permissions:
|
|
273
|
+
issues: write
|
|
274
|
+
steps:
|
|
275
|
+
- name: File one trunk-red issue
|
|
276
|
+
env:
|
|
277
|
+
GH_TOKEN: ${{ github.token }}
|
|
278
|
+
REPO: ${{ github.repository }}
|
|
279
|
+
SHA: ${{ needs.plan.outputs.sha }}
|
|
280
|
+
SINCE: ${{ needs.plan.outputs.since }}
|
|
281
|
+
WORKFLOW: ${{ github.workflow }}
|
|
282
|
+
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
|
283
|
+
run: |
|
|
284
|
+
set -uo pipefail
|
|
285
|
+
title="Nightly heavy lane red: $WORKFLOW"
|
|
286
|
+
if ! open="$(gh issue list -R "$REPO" --state open --search "\"$title\" in:title" --json number,title \
|
|
287
|
+
--jq "[.[] | select(.title == \"$title\")][0].number // \"\"")"; then
|
|
288
|
+
echo "::error::cannot read this repo's issues — nothing filed; the red run is the only report"
|
|
289
|
+
exit 1
|
|
290
|
+
fi
|
|
291
|
+
if [ -n "$open" ]; then
|
|
292
|
+
echo "::notice::#$open already reports this lane red — not filing another."
|
|
293
|
+
exit 0
|
|
294
|
+
fi
|
|
295
|
+
if [ -n "$SINCE" ]; then
|
|
296
|
+
range="[\`${SINCE:0:12}..${SHA:0:12}\`]($GITHUB_SERVER_URL/$REPO/compare/$SINCE...$SHA) — the commits since the last green nightly"
|
|
297
|
+
else
|
|
298
|
+
range="up to \`${SHA:0:12}\` — no green nightly on record to bound it"
|
|
299
|
+
fi
|
|
300
|
+
gh label create trunk-red -R "$REPO" --color B60205 --description "Trunk fails a check" 2>/dev/null || true
|
|
301
|
+
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")"
|
|
302
|
+
gh issue create -R "$REPO" --title "$title" --label trunk-red --body "$body"
|