@futurelastic/colab-handbook 1.13.0-rc.4 → 1.13.0-rc.41
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 +50 -20
- package/README.vi.md +53 -23
- package/audit/audit.mjs +128 -16
- package/package.json +2 -1
- package/templates/README.md +15 -3
- package/templates/ci-laravel.yml +184 -30
- package/templates/ci-node.yml +327 -26
- package/templates/ci-python.yml +140 -23
- package/templates/deploy-xserver.yml +12 -0
- package/templates/release-auto.yml +68 -4
- package/tools/colab +990 -107
- package/tools/lib/batch-history.js +104 -0
- package/tools/lib/batch-stats.js +277 -0
- package/tools/lib/ci-profile.js +195 -0
- package/tools/lib/ci-verdict.js +13 -5
- package/tools/lib/ci-wait.js +6 -1
- package/tools/lib/codec/claim.js +6 -3
- package/tools/lib/codec/hold.d.ts +8 -1
- package/tools/lib/codec/hold.js +42 -8
- package/tools/lib/codec/labels.js +7 -0
- package/tools/lib/codec/release.js +6 -3
- package/tools/lib/codec/samples.json +61 -0
- package/tools/lib/config-set.js +319 -0
- package/tools/lib/disposition.js +9 -6
- package/tools/lib/docs-only.js +1 -1
- package/tools/lib/engines.js +52 -0
- package/tools/lib/git.js +82 -18
- package/tools/lib/install-check.js +77 -5
- package/tools/lib/journal.js +3 -0
- package/tools/lib/migration-grant.js +19 -2
- package/tools/lib/notify-endpoint.js +114 -59
- package/tools/lib/notify.js +68 -22
- package/tools/lib/release-cut.js +39 -3
- package/tools/lib/release-finalize.js +113 -17
- package/tools/lib/release-policy.js +11 -3
- package/tools/lib/ship-batch.js +109 -2
- package/tools/lib/ship-human-door.js +76 -0
- package/tools/lib/shipguard.js +12 -1
- package/tools/lib/stamp.js +6 -2
- package/tools/lib/template-trunk.js +80 -0
- package/tools/lib/thresholds.js +110 -0
- package/tools/lib/verify-runs.js +117 -4
package/templates/README.md
CHANGED
|
@@ -20,7 +20,7 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
20
20
|
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
|
|
21
21
|
| `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
|
|
22
22
|
| `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
|
|
23
|
-
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily, from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
23
|
+
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
24
24
|
| `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
|
|
25
25
|
| `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
|
|
26
26
|
| `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
|
|
@@ -67,8 +67,11 @@ notice back and print the run they relied on. Three things to keep in a copy:
|
|
|
67
67
|
|
|
68
68
|
- **It needs `contents: read`** on top of `actions: read`, to read the descriptor and the
|
|
69
69
|
commit objects.
|
|
70
|
-
- **The trunk refs in its `if:` mirror `concurrency`'s list.**
|
|
71
|
-
|
|
70
|
+
- **The trunk refs in its `if:` mirror `concurrency`'s list.** The list appears three times in a
|
|
71
|
+
copy: the `group:`, `cancel-in-progress:`, and this `if:` (#512 gave the trunk its own
|
|
72
|
+
per-run group, so a pending trunk run is never replaced). On a repo whose trunk has another
|
|
73
|
+
name, edit all three. Until you do, the guard simply never fires on trunk — nothing breaks;
|
|
74
|
+
but a trunk left out of `group:` and `cancel-in-progress:` has its runs cancelled.
|
|
72
75
|
- **Never put a trunk-only job behind it.** Publish, deploy and release jobs must run whatever
|
|
73
76
|
the guard says. Give them their own `if:` that does not read `needs.dedupe`.
|
|
74
77
|
|
|
@@ -302,3 +305,12 @@ runner is infrastructure, not a throwaway VM.
|
|
|
302
305
|
service context (`job.services.mysql.ports['3306']`), threading it through your
|
|
303
306
|
env. A fixed `3306:3306` works exactly until the first job lands on a runner
|
|
304
307
|
that already listens there.
|
|
308
|
+
|
|
309
|
+
### One run per commit — why the CI templates have no `pull_request` trigger (#512)
|
|
310
|
+
|
|
311
|
+
The three `ci-*` templates trigger on `push: ['**']` and `workflow_dispatch`. A same-repo PR
|
|
312
|
+
commit gets the push run and nothing else; a `pull_request` trigger beside it ran the suite twice
|
|
313
|
+
and let the later run, which tests the merge ref, decide the verdict. Two edits belong to a copy:
|
|
314
|
+
a repo that goes back to trunk-only push restores `pull_request: branches: [<trunk>]`, and a repo
|
|
315
|
+
that accepts fork PRs keeps one (a fork's push never runs a workflow here). Detail:
|
|
316
|
+
`CONVENTIONS.md` §4, *Branch CI*.
|
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,12 +152,17 @@ 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.
|
|
137
160
|
dedupe:
|
|
138
161
|
name: Already tested at this sha or tree?
|
|
139
162
|
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
140
163
|
if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
|
|
141
164
|
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
165
|
+
timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
|
|
142
166
|
permissions:
|
|
143
167
|
actions: read
|
|
144
168
|
contents: read
|
|
@@ -155,9 +179,34 @@ jobs:
|
|
|
155
179
|
SHA: ${{ github.sha }}
|
|
156
180
|
CREATED: ${{ github.event.created }}
|
|
157
181
|
REF_NAME: ${{ github.ref_name }}
|
|
182
|
+
GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
|
|
158
183
|
run: |
|
|
159
184
|
tested=false
|
|
160
185
|
cited=
|
|
186
|
+
# #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
|
|
187
|
+
# the trunk ref is `skipped` on every branch push and a skipped job does not fail the
|
|
188
|
+
# run, so citing that run would skip the trunk-only job on trunk a second time.
|
|
189
|
+
reusable() {
|
|
190
|
+
if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
|
|
191
|
+
--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
|
|
192
|
+
echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
|
|
193
|
+
return 1
|
|
194
|
+
elif [ -n "$SK" ]; then
|
|
195
|
+
echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
|
|
196
|
+
return 1
|
|
197
|
+
fi
|
|
198
|
+
}
|
|
199
|
+
# The cited run, as "<id> <head sha> <url> <branch>": a green push run of this workflow on
|
|
200
|
+
# another ref of this repo. #552: one at THIS sha first (a `ship-batch/*` run trunk
|
|
201
|
+
# fast-forwarded to), an exact query; else one whose commit has THIS tree (#493).
|
|
202
|
+
same_sha() {
|
|
203
|
+
gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
|
|
204
|
+
--jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null | grep .
|
|
205
|
+
}
|
|
206
|
+
same_tree() {
|
|
207
|
+
gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
|
|
208
|
+
--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\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null
|
|
209
|
+
}
|
|
161
210
|
if ! command -v gh >/dev/null 2>&1; then
|
|
162
211
|
echo "::notice::gh is not installed on this runner — running the full suite (#418)."
|
|
163
212
|
elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
|
|
@@ -172,16 +221,15 @@ jobs:
|
|
|
172
221
|
echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
|
|
173
222
|
elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
|
|
174
223
|
echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
|
|
175
|
-
elif ! CAND="$(
|
|
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
|
|
224
|
+
elif ! CAND="$(same_sha || same_tree)"; then
|
|
177
225
|
echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
|
|
178
226
|
elif [ -z "$CAND" ]; then
|
|
179
|
-
echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
|
|
227
|
+
echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
|
|
180
228
|
else
|
|
181
|
-
read -r CSHA URL BR <<< "$CAND"
|
|
229
|
+
read -r CID CSHA URL BR <<< "$CAND"
|
|
182
230
|
if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
|
|
183
231
|
echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
|
|
184
|
-
|
|
232
|
+
elif reusable "$CID"; then
|
|
185
233
|
tested=true
|
|
186
234
|
cited="$URL"
|
|
187
235
|
echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
|
|
@@ -205,8 +253,9 @@ jobs:
|
|
|
205
253
|
gitleaks:
|
|
206
254
|
name: Secret scan (gitleaks)
|
|
207
255
|
needs: dedupe
|
|
208
|
-
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
256
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
|
|
209
257
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
258
|
+
timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
|
|
210
259
|
steps:
|
|
211
260
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
212
261
|
with:
|
|
@@ -246,8 +295,11 @@ jobs:
|
|
|
246
295
|
build:
|
|
247
296
|
name: Build (Laravel + Vite)
|
|
248
297
|
needs: dedupe
|
|
249
|
-
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
298
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
|
|
250
299
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
300
|
+
timeout-minutes: 45 # a hung build must not hold the runner for the 360-minute default (#572).
|
|
301
|
+
# EDIT: measured (#572): the slowest Laravel adopter's build ran p99 20 / max 26 min. Keep this
|
|
302
|
+
# well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
|
|
251
303
|
# Re-exported so the migrations job below resolves PHP exactly once, here.
|
|
252
304
|
outputs:
|
|
253
305
|
php-version: ${{ steps.toolchain.outputs.php-version }}
|
|
@@ -256,6 +308,37 @@ jobs:
|
|
|
256
308
|
with:
|
|
257
309
|
persist-credentials: false
|
|
258
310
|
|
|
311
|
+
# Decide the test tier (#512). Not an `env:` expression, because the answer depends on
|
|
312
|
+
# the repo's trunk (.github/project.yml), which only exists once the tree is checked out.
|
|
313
|
+
# RUN_TESTS 'true' / 'false' → used as written.
|
|
314
|
+
# 'auto', a pull_request run → on when the PR targets main (copies that restore PRs).
|
|
315
|
+
# 'auto', push or dispatch → on for main, and for every branch when trunk is main
|
|
316
|
+
# (Tier B); off for a dev trunk and its branches (Tier C).
|
|
317
|
+
- name: Decide the test tier
|
|
318
|
+
id: tier
|
|
319
|
+
env:
|
|
320
|
+
DECLARED: ${{ env.RUN_TESTS }}
|
|
321
|
+
EVENT: ${{ github.event_name }}
|
|
322
|
+
REF: ${{ github.ref }}
|
|
323
|
+
BASE_REF: ${{ github.base_ref }}
|
|
324
|
+
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
|
|
325
|
+
run: |
|
|
326
|
+
case "$DECLARED" in
|
|
327
|
+
true|false) run="$DECLARED" ;;
|
|
328
|
+
*)
|
|
329
|
+
trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
|
|
330
|
+
[ -n "$trunk" ] || trunk="$DEFAULT_BRANCH"
|
|
331
|
+
if [ "$EVENT" = "pull_request" ]; then
|
|
332
|
+
[ "$BASE_REF" = "main" ] && run=true || run=false
|
|
333
|
+
elif [ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]; then
|
|
334
|
+
run=true
|
|
335
|
+
else
|
|
336
|
+
run=false
|
|
337
|
+
fi ;;
|
|
338
|
+
esac
|
|
339
|
+
echo "run_tests=$run" >> "$GITHUB_OUTPUT"
|
|
340
|
+
echo "::notice::Pest suite: $run (RUN_TESTS=$DECLARED, event=$EVENT, ref=$REF)"
|
|
341
|
+
|
|
259
342
|
# ---------------------------------------------------------------------------
|
|
260
343
|
# Descriptor check (#416). A value `colab ship` cannot use does not fail there —
|
|
261
344
|
# it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
|
|
@@ -263,23 +346,90 @@ jobs:
|
|
|
263
346
|
# green; only a ship dry run noticed. So the value fails HERE, where the person
|
|
264
347
|
# who changed project.yml is looking. Same rule as `colab ship` and the audit
|
|
265
348
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
266
|
-
# cap is 3: project.schema.md, `ship-batch`.
|
|
349
|
+
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
350
|
+
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
351
|
+
# `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
|
|
267
352
|
# ---------------------------------------------------------------------------
|
|
268
353
|
- name: Descriptor check (.github/project.yml)
|
|
269
354
|
working-directory: ${{ github.workspace }}
|
|
270
355
|
run: |
|
|
271
356
|
[ -f .github/project.yml ] || exit 0
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
357
|
+
# The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
|
|
358
|
+
field() {
|
|
359
|
+
grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
|
|
360
|
+
| sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
|
|
275
361
|
-e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
|
|
276
|
-
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/"
|
|
362
|
+
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
|
|
363
|
+
}
|
|
364
|
+
v="$(field ship-batch)"
|
|
277
365
|
case "$v" in
|
|
278
366
|
''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
279
367
|
*)
|
|
280
368
|
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
|
|
281
369
|
exit 1 ;;
|
|
282
370
|
esac
|
|
371
|
+
# ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
|
|
372
|
+
w="$(field ship-batch-wait)"
|
|
373
|
+
case "$w" in
|
|
374
|
+
''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
|
|
375
|
+
*)
|
|
376
|
+
if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
|
|
377
|
+
echo "ship-batch-wait: $w — ok"
|
|
378
|
+
else
|
|
379
|
+
echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
|
|
380
|
+
exit 1
|
|
381
|
+
fi ;;
|
|
382
|
+
esac
|
|
383
|
+
# ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
|
|
384
|
+
# Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
|
|
385
|
+
f="$(field ci-wait-factor)"
|
|
386
|
+
case "$f" in
|
|
387
|
+
''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
|
|
388
|
+
*)
|
|
389
|
+
if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
|
|
390
|
+
echo "ci-wait-factor: $f — ok"
|
|
391
|
+
else
|
|
392
|
+
echo "::error file=.github/project.yml::ci-wait-factor is '$f', expected a number >= 1 (a multiple of the measured CI duration; omit for 2). colab ship and colab ci-wait ignore any other value and use 2. See project.schema.md, ci-wait-factor."
|
|
393
|
+
exit 1
|
|
394
|
+
fi ;;
|
|
395
|
+
esac
|
|
396
|
+
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
397
|
+
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
398
|
+
# which a test holds this list to.
|
|
399
|
+
# A bad entry falls back to the default everywhere, silently, so it fails here.
|
|
400
|
+
bad=0
|
|
401
|
+
while IFS= read -r t; do
|
|
402
|
+
case "$t" in =*)
|
|
403
|
+
echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
|
|
404
|
+
bad=1; continue ;;
|
|
405
|
+
esac
|
|
406
|
+
k="${t%%:*}"
|
|
407
|
+
n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
408
|
+
max=999999999
|
|
409
|
+
case "$k" in
|
|
410
|
+
hot-file-count|claude-md-line-multiple) min=2 ;;
|
|
411
|
+
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
|
|
412
|
+
claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
|
|
413
|
+
batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
|
|
414
|
+
*) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
|
|
415
|
+
bad=1; continue ;;
|
|
416
|
+
esac
|
|
417
|
+
case "$n" in ''|'~'|null) continue ;; esac
|
|
418
|
+
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
|
|
419
|
+
echo "thresholds.$k: $n — ok"
|
|
420
|
+
else
|
|
421
|
+
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number from $min to $max. Every reader ignores it (a batch-* key is then not judged; any other uses its default). See project.schema.md, thresholds."
|
|
422
|
+
bad=1
|
|
423
|
+
fi
|
|
424
|
+
done < <(awk '
|
|
425
|
+
/^thresholds[[:space:]]*:/ { b = 1; v = $0
|
|
426
|
+
sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
|
|
427
|
+
if (v != "" && v != "~" && v != "null") print "=" v
|
|
428
|
+
next }
|
|
429
|
+
b && /^[[:space:]]*(#|$)/ { next }
|
|
430
|
+
b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
|
|
431
|
+
{ b = 0 }' .github/project.yml)
|
|
432
|
+
[ "$bad" = 0 ] || exit 1
|
|
283
433
|
|
|
284
434
|
# ---------------------------------------------------------------------------
|
|
285
435
|
# Toolchain resolution. Precedence, highest first:
|
|
@@ -397,6 +547,8 @@ jobs:
|
|
|
397
547
|
coverage: none
|
|
398
548
|
|
|
399
549
|
- name: Composer install
|
|
550
|
+
env:
|
|
551
|
+
RUN_TESTS: ${{ steps.tier.outputs.run_tests }}
|
|
400
552
|
run: |
|
|
401
553
|
# --no-scripts: the post-autoload-dump hook runs `package:discover`, which
|
|
402
554
|
# boots the app — and the app cannot boot until the .env below exists.
|
|
@@ -438,14 +590,14 @@ jobs:
|
|
|
438
590
|
npm run build
|
|
439
591
|
|
|
440
592
|
- name: Run migrations against sqlite
|
|
441
|
-
if:
|
|
593
|
+
if: steps.tier.outputs.run_tests == 'true'
|
|
442
594
|
run: |
|
|
443
595
|
# Migrations must apply cleanly from zero. This is the cheapest way to catch
|
|
444
596
|
# a migration that only works against an already-populated database.
|
|
445
597
|
php artisan migrate --force
|
|
446
598
|
|
|
447
599
|
- name: Test (Pest)
|
|
448
|
-
if:
|
|
600
|
+
if: steps.tier.outputs.run_tests == 'true'
|
|
449
601
|
run: |
|
|
450
602
|
if [ -f vendor/bin/pest ]; then
|
|
451
603
|
vendor/bin/pest --ci
|
|
@@ -488,6 +640,8 @@ jobs:
|
|
|
488
640
|
# form would skip this job on exactly the runs it exists for (#418).
|
|
489
641
|
if: ${{ !cancelled() && needs.build.result == 'success' }}
|
|
490
642
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
643
|
+
timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
|
|
644
|
+
# EDIT: measured (#572): p99 under 4 min / max 5 min on every adopter. Keep it well above your own p99.
|
|
491
645
|
strategy:
|
|
492
646
|
fail-fast: false
|
|
493
647
|
matrix:
|