@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.10
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 +2 -2
- package/README.vi.md +2 -2
- package/audit/audit.mjs +218 -53
- package/package.json +1 -1
- package/templates/README.md +18 -3
- package/templates/ci-laravel.yml +360 -40
- package/templates/ci-node.yml +491 -35
- package/templates/ci-python.yml +301 -32
- package/templates/deploy-container-run.mjs +17 -3
- package/templates/deploy-xserver.yml +12 -0
- package/templates/instruction-files.yml +16 -0
- package/templates/pre-commit-instruction-files +55 -0
- package/templates/release-auto.yml +16 -3
- package/tools/colab +884 -98
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/audit-cache.js +277 -0
- package/tools/lib/batch-stats.js +66 -43
- package/tools/lib/ci-cure.js +10 -1
- package/tools/lib/claim-comments.js +3 -2
- package/tools/lib/codec/decision.d.ts +7 -0
- package/tools/lib/codec/decision.js +54 -0
- package/tools/lib/codec/hold.d.ts +8 -1
- package/tools/lib/codec/hold.js +42 -8
- package/tools/lib/codec/release.js +6 -3
- package/tools/lib/codec/samples.json +45 -0
- package/tools/lib/config-set.js +4 -3
- package/tools/lib/cure-diff.js +27 -1
- package/tools/lib/decision-record.js +42 -0
- package/tools/lib/docs-only.js +47 -0
- package/tools/lib/git.js +57 -8
- package/tools/lib/grant-policy.js +133 -0
- package/tools/lib/instruction-file.js +75 -0
- package/tools/lib/instruction-gate.js +179 -0
- package/tools/lib/landed-prs.js +58 -0
- package/tools/lib/migration-grant.js +29 -5
- package/tools/lib/owner-policy.js +110 -0
- package/tools/lib/release-cut.js +127 -10
- package/tools/lib/release-finalize.js +66 -5
- package/tools/lib/ship-batch.js +188 -14
- package/tools/lib/ship-handoff.js +212 -0
- package/tools/lib/stamp.js +6 -2
- package/tools/lib/template-trunk.js +80 -0
- package/tools/lib/tree-green.js +21 -4
- package/tools/lib/workflow-triggers.js +57 -0
package/templates/ci-laravel.yml
CHANGED
|
@@ -67,31 +67,50 @@ on:
|
|
|
67
67
|
# dev is the trunk, so a main-only trigger runs zero checks on the branch you
|
|
68
68
|
# merge into, and nothing looks broken (CONVENTIONS.md §7).
|
|
69
69
|
branches: ['**']
|
|
70
|
-
pull_request
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
70
|
+
# No `pull_request:` here (#512). A branch with an open PR in this repository already
|
|
71
|
+
# has a push run at the same head, and a `pull_request` run beside it doubled the CI
|
|
72
|
+
# per commit while testing a merge ref instead of the sha that lands. Readers keep only
|
|
73
|
+
# the newest run per workflow at a sha, so that second run also decided the verdict.
|
|
74
|
+
# EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
|
|
75
|
+
# has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
|
|
76
|
+
# only branch run (CONVENTIONS.md §4, "Branch CI"), so also delete the fork-PR term
|
|
77
|
+
# (`github.event_name != 'pull_request' || …`) from every job's `if:` below, or it skips that run.
|
|
78
|
+
# EDIT: fork PRs (#514). A push to a fork never runs a workflow here, so a repo that takes
|
|
79
|
+
# PRs from forks needs `pull_request`. Uncomment it there. Every suite job below already
|
|
80
|
+
# carries `github.event.pull_request.head.repo.full_name != github.repository` for a PR
|
|
81
|
+
# event, so a same-repo PR's run skips every job (its push run is the one that tests) and a
|
|
82
|
+
# fork PR's run tests. A skipped run never stands for a workflow that has a run that ran
|
|
83
|
+
# (CONVENTIONS.md §4, "Branch CI"). Check every reader of your CI agrees before you uncomment.
|
|
84
|
+
# pull_request:
|
|
85
|
+
# branches: ['**']
|
|
74
86
|
# A promotion pushed by the release workflow's token triggers no push run, so that workflow
|
|
75
87
|
# dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
|
|
76
88
|
workflow_dispatch:
|
|
77
89
|
|
|
78
90
|
# One live run per branch: a new push cancels the superseded run on the same ref.
|
|
79
91
|
# Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
|
|
80
|
-
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI").
|
|
81
|
-
# group
|
|
82
|
-
#
|
|
83
|
-
#
|
|
92
|
+
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
|
|
93
|
+
# group of its own (the run id): GitHub cancels an older run that is still PENDING in a
|
|
94
|
+
# group even when cancel-in-progress is false, so a third quick merge would otherwise
|
|
95
|
+
# drop the second one's run before it ever started (#512).
|
|
96
|
+
# EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
|
|
97
|
+
# cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
|
|
98
|
+
# name; one left off this list gets its trunk runs cancelled. `colab template` writes these
|
|
99
|
+
# from the `trunk:` in .github/project.yml and prints what it wrote (#526).
|
|
84
100
|
concurrency:
|
|
85
|
-
group: ci-${{ github.ref }}
|
|
101
|
+
group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
|
|
86
102
|
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
|
|
87
103
|
|
|
88
104
|
env:
|
|
89
|
-
#
|
|
90
|
-
#
|
|
91
|
-
#
|
|
92
|
-
#
|
|
93
|
-
#
|
|
94
|
-
|
|
105
|
+
# Whether the Pest suite runs. 'auto' is decided by the "Decide the test tier" step in
|
|
106
|
+
# `build` (#512). Light CI on a dev trunk and its branches (does it build at all,
|
|
107
|
+
# ~2 min); heavy CI on main, where the Pest suite gates a release. On Tier C main IS
|
|
108
|
+
# production — promotion is the deploy — so this suite is the last gate before users,
|
|
109
|
+
# not a release formality. When main is the trunk (Tier B) every branch push runs the
|
|
110
|
+
# suite too: this workflow has no `pull_request` run any more, and that run used to be
|
|
111
|
+
# the only place a Tier B branch got its tests.
|
|
112
|
+
# EDIT: set to a literal 'true' to always run the suite, 'false' to never run it.
|
|
113
|
+
RUN_TESTS: auto
|
|
95
114
|
# EDIT: bump deliberately, not automatically.
|
|
96
115
|
GITLEAKS_VERSION: "8.30.1"
|
|
97
116
|
# EDIT: match the app's APP_NAME. Leave empty if the build does not read it.
|
|
@@ -133,17 +152,35 @@ jobs:
|
|
|
133
152
|
# depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
|
|
134
153
|
# descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
|
|
135
154
|
# any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
|
|
136
|
-
#
|
|
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).
|
|
137
173
|
dedupe:
|
|
138
174
|
name: Already tested at this sha or tree?
|
|
139
175
|
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
140
176
|
if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
|
|
141
177
|
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
178
|
+
timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
|
|
142
179
|
permissions:
|
|
143
180
|
actions: read
|
|
144
181
|
contents: read
|
|
145
182
|
outputs:
|
|
146
|
-
tested: ${{ steps.check.outputs.tested }}
|
|
183
|
+
tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
|
|
147
184
|
cited: ${{ steps.check.outputs.cited }}
|
|
148
185
|
steps:
|
|
149
186
|
- name: Look for a green run of this workflow at this sha or tree
|
|
@@ -155,9 +192,58 @@ jobs:
|
|
|
155
192
|
SHA: ${{ github.sha }}
|
|
156
193
|
CREATED: ${{ github.event.created }}
|
|
157
194
|
REF_NAME: ${{ github.ref_name }}
|
|
195
|
+
GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
|
|
158
196
|
run: |
|
|
159
197
|
tested=false
|
|
160
198
|
cited=
|
|
199
|
+
# #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
|
|
200
|
+
# the trunk ref is `skipped` on every branch push and a skipped job does not fail the
|
|
201
|
+
# run, so citing that run would skip the trunk-only job on trunk a second time.
|
|
202
|
+
reusable() {
|
|
203
|
+
if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
|
|
204
|
+
--jq 'if .total_count > (.jobs | length) then "(more than 100 jobs)" else [.jobs[] | select(.conclusion == "skipped" and .name != env.GUARD_NAME) | .name] | join(", ") end' 2>/dev/null)"; then
|
|
205
|
+
echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
|
|
206
|
+
return 1
|
|
207
|
+
elif [ -n "$SK" ]; then
|
|
208
|
+
echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
|
|
209
|
+
return 1
|
|
210
|
+
fi
|
|
211
|
+
}
|
|
212
|
+
# The candidate runs, one per line as "<id> <head sha> <url> <branch>", newest first: green
|
|
213
|
+
# push runs of this workflow on another ref of this repo. #552: those at THIS sha first (a
|
|
214
|
+
# `ship-batch/*` run trunk fast-forwarded to), an exact query; then those whose commit has
|
|
215
|
+
# THIS tree (#493). The query's own per_page bounds the walk (#592).
|
|
216
|
+
same_sha() {
|
|
217
|
+
gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
|
|
218
|
+
--jq ".workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\"" 2>/dev/null
|
|
219
|
+
}
|
|
220
|
+
same_tree() {
|
|
221
|
+
gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
|
|
222
|
+
--jq ".workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\"" 2>/dev/null
|
|
223
|
+
}
|
|
224
|
+
# #592: cite the newest candidate on stdin that passes every check. One that fails a check
|
|
225
|
+
# is passed over, not the end of the search: the newest green run can be a skip-chained one
|
|
226
|
+
# (#511) while an older run at the same sha or tree ran every job. A run already tried (the
|
|
227
|
+
# sha query's runs reappear in the tree listing) is not tried twice.
|
|
228
|
+
cite() {
|
|
229
|
+
local CID CSHA URL BR CTREE
|
|
230
|
+
while read -r CID CSHA URL BR; do
|
|
231
|
+
[ -n "$CID" ] || continue
|
|
232
|
+
case " $TRIED " in *" $CID "*) continue ;; esac
|
|
233
|
+
TRIED="$TRIED $CID"
|
|
234
|
+
if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
|
|
235
|
+
echo "::notice::Could not confirm the tree of $CSHA — passing over run $CID (#493)."
|
|
236
|
+
elif reusable "$CID"; then
|
|
237
|
+
tested=true
|
|
238
|
+
cited="$URL"
|
|
239
|
+
echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
|
|
240
|
+
echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
|
|
241
|
+
echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
|
|
242
|
+
return 0
|
|
243
|
+
fi
|
|
244
|
+
done
|
|
245
|
+
return 1
|
|
246
|
+
}
|
|
161
247
|
if ! command -v gh >/dev/null 2>&1; then
|
|
162
248
|
echo "::notice::gh is not installed on this runner — running the full suite (#418)."
|
|
163
249
|
elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
|
|
@@ -172,21 +258,17 @@ jobs:
|
|
|
172
258
|
echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
|
|
173
259
|
elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
|
|
174
260
|
echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
|
|
175
|
-
elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
|
|
176
|
-
--jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
|
|
177
|
-
echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
|
|
178
|
-
elif [ -z "$CAND" ]; then
|
|
179
|
-
echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
|
|
180
261
|
else
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
echo "
|
|
189
|
-
|
|
262
|
+
TRIED=
|
|
263
|
+
SC="$(same_sha)" || SC= # the sha query failing falls through to the tree listing (#552)
|
|
264
|
+
if [ -n "$SC" ] && cite <<< "$SC"; then
|
|
265
|
+
:
|
|
266
|
+
elif ! TC="$(same_tree)"; then
|
|
267
|
+
echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
|
|
268
|
+
elif [ -z "$SC$TC" ]; then
|
|
269
|
+
echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
|
|
270
|
+
elif ! cite <<< "$TC"; then
|
|
271
|
+
echo "No green run of this workflow at sha $SHA or tree $OURS can be cited — running the full suite (#592)."
|
|
190
272
|
fi
|
|
191
273
|
fi
|
|
192
274
|
elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
|
|
@@ -201,12 +283,167 @@ jobs:
|
|
|
201
283
|
fi
|
|
202
284
|
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
203
285
|
[ -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"
|
|
204
440
|
|
|
205
441
|
gitleaks:
|
|
206
442
|
name: Secret scan (gitleaks)
|
|
207
443
|
needs: dedupe
|
|
208
|
-
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
444
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
|
|
209
445
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
446
|
+
timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
|
|
210
447
|
steps:
|
|
211
448
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
212
449
|
with:
|
|
@@ -246,8 +483,11 @@ jobs:
|
|
|
246
483
|
build:
|
|
247
484
|
name: Build (Laravel + Vite)
|
|
248
485
|
needs: dedupe
|
|
249
|
-
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
486
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
|
|
250
487
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
488
|
+
timeout-minutes: 45 # a hung build must not hold the runner for the 360-minute default (#572).
|
|
489
|
+
# EDIT: measured (#572): the slowest Laravel adopter's build ran p99 20 / max 26 min. Keep this
|
|
490
|
+
# well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
|
|
251
491
|
# Re-exported so the migrations job below resolves PHP exactly once, here.
|
|
252
492
|
outputs:
|
|
253
493
|
php-version: ${{ steps.toolchain.outputs.php-version }}
|
|
@@ -256,15 +496,48 @@ jobs:
|
|
|
256
496
|
with:
|
|
257
497
|
persist-credentials: false
|
|
258
498
|
|
|
499
|
+
# Decide the test tier (#512). Not an `env:` expression, because the answer depends on
|
|
500
|
+
# the repo's trunk (.github/project.yml), which only exists once the tree is checked out.
|
|
501
|
+
# RUN_TESTS 'true' / 'false' → used as written.
|
|
502
|
+
# 'auto', a pull_request run → on when the PR targets main (copies that restore PRs).
|
|
503
|
+
# 'auto', push or dispatch → on for main, and for every branch when trunk is main
|
|
504
|
+
# (Tier B); off for a dev trunk and its branches (Tier C).
|
|
505
|
+
- name: Decide the test tier
|
|
506
|
+
id: tier
|
|
507
|
+
env:
|
|
508
|
+
DECLARED: ${{ env.RUN_TESTS }}
|
|
509
|
+
EVENT: ${{ github.event_name }}
|
|
510
|
+
REF: ${{ github.ref }}
|
|
511
|
+
BASE_REF: ${{ github.base_ref }}
|
|
512
|
+
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
|
|
513
|
+
run: |
|
|
514
|
+
case "$DECLARED" in
|
|
515
|
+
true|false) run="$DECLARED" ;;
|
|
516
|
+
*)
|
|
517
|
+
trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
|
|
518
|
+
[ -n "$trunk" ] || trunk="$DEFAULT_BRANCH"
|
|
519
|
+
if [ "$EVENT" = "pull_request" ]; then
|
|
520
|
+
[ "$BASE_REF" = "main" ] && run=true || run=false
|
|
521
|
+
elif [ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]; then
|
|
522
|
+
run=true
|
|
523
|
+
else
|
|
524
|
+
run=false
|
|
525
|
+
fi ;;
|
|
526
|
+
esac
|
|
527
|
+
echo "run_tests=$run" >> "$GITHUB_OUTPUT"
|
|
528
|
+
echo "::notice::Pest suite: $run (RUN_TESTS=$DECLARED, event=$EVENT, ref=$REF)"
|
|
529
|
+
|
|
259
530
|
# ---------------------------------------------------------------------------
|
|
260
531
|
# Descriptor check (#416). A value `colab ship` cannot use does not fail there —
|
|
261
|
-
# it fails closed to the safe default, silently. `ship-batch: 5` (the cap
|
|
532
|
+
# it fails closed to the safe default, silently. `ship-batch: 5` (the cap was 3)
|
|
262
533
|
# once turned every landing in a busy repo back to serial while this CI stayed
|
|
263
534
|
# green; only a ship dry run noticed. So the value fails HERE, where the person
|
|
264
535
|
# who changed project.yml is looking. Same rule as `colab ship` and the audit
|
|
265
|
-
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–
|
|
266
|
-
# cap is
|
|
536
|
+
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–8. Why the
|
|
537
|
+
# cap is 8: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
267
538
|
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
539
|
+
# `ship-batch-steps` (#557, parseShipBatchSteps): absent/empty/null, or ascending
|
|
540
|
+
# whole numbers within ship-batch — 2,4,8 or [2, 4, 8].
|
|
268
541
|
# `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
|
|
269
542
|
# ---------------------------------------------------------------------------
|
|
270
543
|
- name: Descriptor check (.github/project.yml)
|
|
@@ -280,11 +553,26 @@ jobs:
|
|
|
280
553
|
}
|
|
281
554
|
v="$(field ship-batch)"
|
|
282
555
|
case "$v" in
|
|
283
|
-
''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
556
|
+
''|'~'|null|1|2|3|4|5|6|7|8) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
284
557
|
*)
|
|
285
|
-
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-
|
|
558
|
+
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-8 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 8: project.schema.md, ship-batch."
|
|
286
559
|
exit 1 ;;
|
|
287
560
|
esac
|
|
561
|
+
# ship-batch-steps (#557): ascending whole numbers, each within ship-batch (the ceiling read above).
|
|
562
|
+
s="$(field ship-batch-steps)"
|
|
563
|
+
case "$s" in
|
|
564
|
+
''|'~'|null) echo "ship-batch-steps: absent — ok (fixed size)" ;;
|
|
565
|
+
*)
|
|
566
|
+
case "$v" in ''|'~'|null) ceil=1 ;; *) ceil="$v" ;; esac
|
|
567
|
+
list="$(printf '%s' "$s" | sed -E -e 's/^\[(.*)\]$/\1/' -e 's/^[[:space:]]+//' -e 's/[[:space:]]+$//' -e 's/[[:space:]]*,[[:space:]]*/,/g')"
|
|
568
|
+
if printf '%s\n' "$list" | grep -Eq '^[1-9][0-9]*(,[1-9][0-9]*)*$' \
|
|
569
|
+
&& printf '%s\n' "$list" | tr ',' '\n' | awk -v n="$ceil" '{ if ($1 + 0 <= p || $1 + 0 > n + 0) bad = 1; p = $1 + 0 } END { exit bad }'; then
|
|
570
|
+
echo "ship-batch-steps: $list — ok"
|
|
571
|
+
else
|
|
572
|
+
echo "::error file=.github/project.yml::ship-batch-steps is '$s', expected strictly ascending whole numbers within ship-batch ($ceil), like 2,4,8 (omit for a fixed size). colab ship ignores any other value and uses the fixed size. See project.schema.md, ship-batch-steps."
|
|
573
|
+
exit 1
|
|
574
|
+
fi ;;
|
|
575
|
+
esac
|
|
288
576
|
# ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
|
|
289
577
|
w="$(field ship-batch-wait)"
|
|
290
578
|
case "$w" in
|
|
@@ -463,7 +751,31 @@ jobs:
|
|
|
463
751
|
extensions: mbstring, sqlite3, pdo_sqlite, bcmath, intl # EDIT: add what this app needs.
|
|
464
752
|
coverage: none
|
|
465
753
|
|
|
754
|
+
# Package cache (#571): Composer's download cache, on only on a GitHub-hosted runner AND
|
|
755
|
+
# with composer.lock present. Both halves are load-bearing:
|
|
756
|
+
# - No composer.lock → nothing stable to key on; every run would save a fresh entry.
|
|
757
|
+
# - Self-hosted → off. A persistent runner already keeps Composer's cache dir between
|
|
758
|
+
# jobs; a remote cache on top was measured as a loss, not a saving (#512).
|
|
759
|
+
# Two NEW steps, both skipped where the gate is off. "Composer install" keeps its name
|
|
760
|
+
# and its body: `colab ship`'s cure rule matches steps by exact name.
|
|
761
|
+
# EDIT: self-hosted runners are already off; to turn caching off everywhere, delete these
|
|
762
|
+
# two steps.
|
|
763
|
+
- name: Locate Composer cache
|
|
764
|
+
id: composer-cache
|
|
765
|
+
if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
|
|
766
|
+
run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
|
|
767
|
+
|
|
768
|
+
- name: Restore Composer cache
|
|
769
|
+
if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
|
|
770
|
+
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
|
|
771
|
+
with:
|
|
772
|
+
path: ${{ steps.composer-cache.outputs.dir }}
|
|
773
|
+
key: composer-${{ runner.os }}-${{ hashFiles('composer.lock') }}
|
|
774
|
+
restore-keys: composer-${{ runner.os }}-
|
|
775
|
+
|
|
466
776
|
- name: Composer install
|
|
777
|
+
env:
|
|
778
|
+
RUN_TESTS: ${{ steps.tier.outputs.run_tests }}
|
|
467
779
|
run: |
|
|
468
780
|
# --no-scripts: the post-autoload-dump hook runs `package:discover`, which
|
|
469
781
|
# boots the app — and the app cannot boot until the .env below exists.
|
|
@@ -495,9 +807,15 @@ jobs:
|
|
|
495
807
|
# stderr and reports only "Command failed".
|
|
496
808
|
php artisan wayfinder:generate $WAYFINDER_ARGS
|
|
497
809
|
|
|
810
|
+
# npm cache (#571): the same gate as the Composer cache above — GitHub-hosted AND
|
|
811
|
+
# package-lock.json present (`cache: npm` fails the step without one). The automatic
|
|
812
|
+
# `packageManager` cache is pinned to the same condition so it cannot override it.
|
|
813
|
+
# EDIT: to turn it off everywhere, replace both expressions with '' and false.
|
|
498
814
|
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
|
|
499
815
|
with:
|
|
500
816
|
node-version: ${{ steps.toolchain.outputs.node-version }}
|
|
817
|
+
cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
|
|
818
|
+
package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
|
|
501
819
|
|
|
502
820
|
- name: Build frontend assets (Vite)
|
|
503
821
|
run: |
|
|
@@ -505,14 +823,14 @@ jobs:
|
|
|
505
823
|
npm run build
|
|
506
824
|
|
|
507
825
|
- name: Run migrations against sqlite
|
|
508
|
-
if:
|
|
826
|
+
if: steps.tier.outputs.run_tests == 'true'
|
|
509
827
|
run: |
|
|
510
828
|
# Migrations must apply cleanly from zero. This is the cheapest way to catch
|
|
511
829
|
# a migration that only works against an already-populated database.
|
|
512
830
|
php artisan migrate --force
|
|
513
831
|
|
|
514
832
|
- name: Test (Pest)
|
|
515
|
-
if:
|
|
833
|
+
if: steps.tier.outputs.run_tests == 'true'
|
|
516
834
|
run: |
|
|
517
835
|
if [ -f vendor/bin/pest ]; then
|
|
518
836
|
vendor/bin/pest --ci
|
|
@@ -555,6 +873,8 @@ jobs:
|
|
|
555
873
|
# form would skip this job on exactly the runs it exists for (#418).
|
|
556
874
|
if: ${{ !cancelled() && needs.build.result == 'success' }}
|
|
557
875
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
876
|
+
timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
|
|
877
|
+
# EDIT: measured (#572): p99 under 4 min / max 5 min on every adopter. Keep it well above your own p99.
|
|
558
878
|
strategy:
|
|
559
879
|
fail-fast: false
|
|
560
880
|
matrix:
|