@futurelastic/colab-handbook 1.20.4-rc.9 → 1.21.0-rc.2

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.
@@ -1,10 +1,13 @@
1
- # CI (Laravel) — TEMPLATE. Copy me into your repo at .github/workflows/ci.yml.
1
+ # CI (Laravel) — CALLER of the handbook's reusable workflow. Copy me into your repo at .github/workflows/ci.yml.
2
2
  #
3
- # This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
4
- # Edit it freely: rename jobs, add steps, drop the parts you do not need. Nothing
5
- # calls this file remotely and nothing will update it for you — divergence between
6
- # your copy and the handbook is expected and fine. If you find an improvement worth
7
- # sharing, change the handbook template too, but that is a manual, deliberate act.
3
+ # A CALLER since #724, not a copy of the gate. The dedupe gate, the secret scan, the descriptor check
4
+ # of .github/project.yml, the toolchain resolution (project.yml, then the manifest, else FAIL — never a
5
+ # default), the package caches and the quick/full split live once, in the handbook's reusable
6
+ # .github/workflows/ci-light.yml, and a handbook release moves them. What stays yours, and is yours to
7
+ # edit: the triggers and `concurrency` (a called workflow cannot own either, CONVENTIONS.md §7, "One
8
+ # verdict per tree"), the `with:` block, and any job of your own beside the call. `colab template ci-laravel`
9
+ # writes this repo's trunk refs and pins the call to the handbook release it stamps the copy with;
10
+ # `colab update` moves a pristine copy's stamp and pin together.
8
11
  #
9
12
  # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
10
13
  #
@@ -25,7 +28,7 @@
25
28
  # reports only "Command failed", which is unusable for debugging. Running the
26
29
  # artisan command ourselves first means a codegen failure shows its real error.
27
30
  #
28
- # A third job, `migrations`, round-trips the schema (migrate -> rollback -> migrate)
31
+ # A job beside the call, `migrations`, round-trips the schema (migrate -> rollback -> migrate)
29
32
  # on the TEST engine (sqlite) AND the DEPLOY engine (a MariaDB/MySQL service
30
33
  # container). Every case below was measured, and the engines disagree on several of
31
34
  # them — so either engine alone passes a migration the other refuses:
@@ -37,13 +40,21 @@
37
40
  # Not gated on RUN_TESTS: a bad migration is cheapest to fix on the branch that adds or
38
41
  # modifies it, so this runs on every push, not only on main.
39
42
  #
43
+ # What the call runs (ci-light.yml):
44
+ # 0. The gate: already tested at this sha or tree? Then the suite is skipped (one verdict per tree).
45
+ # 1. Secret scan with gitleaks (pinned release binary).
46
+ # 2. Quick: the descriptor check (ship-batch, #416; ship-batch-wait, #555; ci-wait-factor, #564).
47
+ # 3. Full: the `full` script below — the test tier, composer install, the throwaway sqlite .env,
48
+ # wayfinder, the Vite build, then (on the tier) migrate + Pest. Install runs inside it, not in
49
+ # `install`, so the quick job does not pay for a Composer and npm install it never uses.
50
+ #
40
51
  # LIGHT LANE (#607): this file runs on every push and is what `colab ship` reads. Keep it
41
52
  # fast — secret scan, build, typecheck/lint, the fast tests (target: under 5 minutes).
42
53
  # The full suite, integration, e2e and load tests belong in the HEAVY lane,
43
54
  # templates/ci-laravel-heavy.yml copied to .github/workflows/ci-heavy.yml: it runs nightly
44
- # and on every release candidate/tag, never per merge. Tests are light unless marked heavy:
55
+ # and on every release candidate/tag, never per merge. The heavy lane is still a copy (#724 kept it
56
+ # one: it is not what drifted). Tests are light unless marked heavy:
45
57
  # the Pest/PHPUnit group `heavy` (`->group('heavy')` or `#[Group('heavy')]`).
46
-
47
58
  name: CI
48
59
 
49
60
  on:
@@ -73,10 +84,11 @@ on:
73
84
  # the newest run per workflow at a sha, so that second run also decided the verdict.
74
85
  # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
75
86
  # 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.
87
+ # only branch run (CONVENTIONS.md §4, "Branch CI"). But the called workflow skips a SAME-repo
88
+ # PR run (its jobs carry the fork-PR term), so with this caller that only helps fork PRs: on
89
+ # trunk-only push a same-repo branch gets no run at all. Keep '**' with the caller.
78
90
  # 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
91
+ # PRs from forks needs `pull_request`. Uncomment it there. Every job of the called workflow
80
92
  # carries `github.event.pull_request.head.repo.full_name != github.repository` for a PR
81
93
  # event, so a same-repo PR's run skips every job (its push run is the one that tests) and a
82
94
  # fork PR's run tests. A skipped run never stands for a workflow that has a run that ran
@@ -94,688 +106,123 @@ on:
94
106
  # group even when cancel-in-progress is false, so a third quick merge would otherwise
95
107
  # drop the second one's run before it ever started (#512).
96
108
  # 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
109
+ # cancel-in-progress, and in the call's `trunk-branches` input below. A Tier C trunk may carry any
98
110
  # name; one left off this list gets its trunk runs cancelled. `colab template` writes these
99
111
  # from the `trunk:` in .github/project.yml and prints what it wrote (#526).
100
112
  concurrency:
101
113
  group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
102
114
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
103
115
 
104
- env:
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
114
- # EDIT: bump deliberately, not automatically.
115
- GITLEAKS_VERSION: "8.30.1"
116
- # EDIT: match the app's APP_NAME. Leave empty if the build does not read it.
117
- VITE_APP_NAME: ""
118
- # EDIT: arguments passed to `php artisan wayfinder:generate`.
119
- WAYFINDER_ARGS: "--with-form"
116
+ # The called jobs can only narrow these: the gate lists this workflow's runs and reads git objects.
117
+ permissions:
118
+ actions: read
119
+ contents: read
120
120
 
121
- # Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
122
- # fresh machine per job. With few self-hosted agents every job is a queue slot,
123
- # jobs from different runs interleave, and trunk can wait behind branch runs.
124
- # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
125
121
  jobs:
126
- # Already tested? This job is the one that concludes `success` when the suite is skipped: a
127
- # run whose jobs ALL skip concludes `skipped`, which `colab ship` reads as not-green.
128
- # - At this SHA (#418): on a ref's first push (a claim push), a green non-PR run of this
129
- # workflow at the same sha means the suite already ran.
130
- # - At this TREE (#493): on a push to trunk, and on the first push of a batch-landing ref
131
- # (`ship-batch/**`, #717), a green push run elsewhere whose commit has the byte-identical tree
132
- # (a squash of a branch that already contained its base) is reused and cited in a
133
- # `tree-already-green` notice. `tree-reuse: off` in .github/project.yml opts out.
134
- # A run that skipped a job (a trunk-only job skips on branches) is never reused (#511) — except
135
- # a job named in TRUNK_ONLY_JOBS below, which sits outside this gate and runs on trunk anyway.
136
- # So a trunk-only job (publish, deploy, release) never sits behind this gate: put it in a
137
- # workflow of its own, or keep it here ungated and list it (#717).
138
- # The rule this keeps: one CI verdict per git tree (CONVENTIONS.md §7, "One verdict per tree").
139
- # Any doubt — no run, red, an API error — runs the full suite; this job never fails the run.
140
- dedupe:
141
- name: Already tested at this sha or tree?
142
- # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
143
- if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
144
- runs-on: ubuntu-latest # EDIT: self-hosted → the class of the jobs below, never a host (CONVENTIONS.md §7, "Runner classes"); it needs `gh`.
145
- timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
146
- permissions:
147
- actions: read
148
- contents: read
149
- outputs:
150
- tested: ${{ steps.check.outputs.tested }}
151
- cited: ${{ steps.check.outputs.cited }}
152
- steps:
153
- - name: Look for a green run of this workflow at this sha or tree
154
- id: check
155
- env:
156
- GH_TOKEN: ${{ github.token }}
157
- REPO: ${{ github.repository }}
158
- RUN_ID: ${{ github.run_id }}
159
- SHA: ${{ github.sha }}
160
- CREATED: ${{ github.event.created }}
161
- REF_NAME: ${{ github.ref_name }}
162
- GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
163
- # EDIT (#717): the `name:` of every job here that is trunk-only (publish, deploy, release) and
164
- # sits OUTSIDE this gate — its `if:` never reads `needs.dedupe.outputs.tested`, so it runs on
165
- # trunk whatever this guard decides. Comma-separated, exact names as a run lists them. A cited
166
- # branch run may have skipped these and is still reused. Never list a suite job or any job
167
- # behind the gate: it would then be skipped on trunk twice. Empty = #511 unchanged. Simpler
168
- # still: keep trunk-only jobs in a workflow of their own (CONVENTIONS.md §7, "One verdict per tree").
169
- TRUNK_ONLY_JOBS: ""
170
- run: |
171
- tested=false
172
- cited=
173
- # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
174
- # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
175
- # run, so citing that run would skip the trunk-only job on trunk a second time — unless
176
- # the job is named in TRUNK_ONLY_JOBS: it sits outside the gate and runs here anyway (#717).
177
- reusable() {
178
- if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
179
- --jq 'if .total_count > (.jobs | length) then "(more than 100 jobs)" else [.jobs[] | select(.conclusion == "skipped" and .name != env.GUARD_NAME) | .name | select(. as $n | any((env.TRUNK_ONLY_JOBS // "") | split(",")[] | gsub("^\\s+|\\s+$"; ""); . == $n) | not)] | join(", ") end' 2>/dev/null)"; then
180
- echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
181
- return 1
182
- elif [ -n "$SK" ]; then
183
- echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
184
- return 1
185
- fi
186
- }
187
- # The candidate runs, one per line as "<id> <head sha> <url> <branch>", newest first: green
188
- # push runs of this workflow on another ref of this repo. #552: those at THIS sha first (a
189
- # `ship-batch/*` run trunk fast-forwarded to), an exact query; then those whose commit has
190
- # THIS tree (#493). The query's own per_page bounds the walk (#592).
191
- same_sha() {
192
- gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
193
- --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
194
- }
195
- same_tree() {
196
- gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
197
- --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
198
- }
199
- # #592: cite the newest candidate on stdin that passes every check. One that fails a check
200
- # is passed over, not the end of the search: the newest green run can be a skip-chained one
201
- # (#511) while an older run at the same sha or tree ran every job. A run already tried (the
202
- # sha query's runs reappear in the tree listing) is not tried twice.
203
- cite() {
204
- local CID CSHA URL BR CTREE
205
- while read -r CID CSHA URL BR; do
206
- [ -n "$CID" ] || continue
207
- case " $TRIED " in *" $CID "*) continue ;; esac
208
- TRIED="$TRIED $CID"
209
- if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
210
- echo "::notice::Could not confirm the tree of $CSHA — passing over run $CID (#493)."
211
- elif reusable "$CID"; then
212
- tested=true
213
- cited="$URL"
214
- echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
215
- echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
216
- echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
217
- return 0
218
- fi
219
- done
220
- return 1
221
- }
222
- if ! command -v gh >/dev/null 2>&1; then
223
- echo "::notice::gh is not installed on this runner — running the full suite (#418)."
224
- elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
225
- echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
226
- elif [ "${CREATED:-}" = "false" ] || [[ "$REF_NAME" == ship-batch/* ]]; then
227
- # Tree mode (#493): a non-creating push to trunk, or the creating push of a batch-landing
228
- # ref (#717), whose new sha often carries a tree a member branch already passed. Same
229
- # checks either way; only the trunk check is the ref's own. Every branch below but one
230
- # runs the suite.
231
- if ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
232
- echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#493)."
233
- elif grep -Eq '^tree-reuse[[:space:]]*:' <<< "$DESC"; then
234
- echo "::notice::tree-reuse is declared in .github/project.yml — running the full suite (#493)."
235
- elif [ "${CREATED:-}" = "false" ] && [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
236
- echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
237
- elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
238
- echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
122
+ ci:
123
+ # Pinned to a handbook release, never a branch: a caller tracking `main` would take every gate
124
+ # change the moment it merges there, untested against this repo. Move the tag deliberately
125
+ # (`colab update` refreshes a pristine copy to the current release).
126
+ uses: futurelastic/colab-handbook/.github/workflows/ci-light.yml@HANDBOOK_TAG
127
+ with:
128
+ trunk-branches: '["main","dev"]'
129
+ toolchain: php,node
130
+ # sqlite3 + pdo_sqlite are what the throwaway bootstrap below runs on.
131
+ php-extensions: mbstring, sqlite3, pdo_sqlite, bcmath, intl # EDIT: add what this app needs.
132
+ install: "" # inside `full`: the test tier decides --no-dev, and the app must not boot before its .env
133
+ full: |
134
+ # EDIT: whether the Pest suite runs. 'auto' (#512): light CI on a dev trunk and its branches
135
+ # (does it build at all, ~2 min); the suite on main, where it gates a release. On Tier C main
136
+ # IS production — promotion is the deploy — so this suite is the last gate before users. When
137
+ # main is the trunk (Tier B) every branch push runs the suite too. 'true' always, 'false' never.
138
+ RUN_TESTS=auto
139
+ # EDIT: match the app's APP_NAME. Leave empty if the build does not read it.
140
+ export VITE_APP_NAME=""
141
+ # EDIT: arguments passed to `php artisan wayfinder:generate`.
142
+ WAYFINDER_ARGS="--with-form"
143
+
144
+ # ── the test tier (#512) — from the repo's trunk (.github/project.yml), else the default branch.
145
+ # 'auto', a pull_request run → on when the PR targets main (copies that restore PRs).
146
+ # 'auto', push or dispatch → on for main, and for every branch when trunk is main
147
+ # (Tier B); off for a dev trunk and its branches (Tier C).
148
+ EVENT="$GITHUB_EVENT_NAME"; REF="$GITHUB_REF"; BASE_REF="${GITHUB_BASE_REF:-}"
149
+ case "$RUN_TESTS" in
150
+ true|false) run="$RUN_TESTS" ;;
151
+ *)
152
+ trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' "$GITHUB_WORKSPACE/.github/project.yml" 2>/dev/null | head -1 || true)"
153
+ [ -n "$trunk" ] || trunk="$(sed -nE 's/.*"default_branch":[[:space:]]*"([^"]+)".*/\1/p' "${GITHUB_EVENT_PATH:-/dev/null}" 2>/dev/null | head -1 || true)"
154
+ if [ "$EVENT" = "pull_request" ]; then
155
+ [ "$BASE_REF" = "main" ] && run=true || run=false
156
+ elif [ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]; then
157
+ run=true
239
158
  else
240
- TRIED=
241
- SC="$(same_sha)" || SC= # the sha query failing falls through to the tree listing (#552)
242
- if [ -n "$SC" ] && cite <<< "$SC"; then
243
- :
244
- elif ! TC="$(same_tree)"; then
245
- echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
246
- elif [ -z "$SC$TC" ]; then
247
- echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
248
- elif ! cite <<< "$TC"; then
249
- echo "No green run of this workflow at sha $SHA or tree $OURS can be cited — running the full suite (#592)."
250
- fi
251
- fi
252
- elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
253
- --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
254
- echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
255
- elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
256
- tested=true
257
- echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
258
- echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
259
- else
260
- echo "No green run of this workflow at $SHA yet — running the full suite."
261
- fi
262
- echo "tested=$tested" >> "$GITHUB_OUTPUT"
263
- [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
264
-
265
- gitleaks:
266
- name: Secret scan (gitleaks)
267
- needs: dedupe
268
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
269
- runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: quick on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
270
- timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
271
- steps:
272
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
273
- with:
274
- # Full history: the scan's range is computed against trunk (origin/<trunk>..HEAD), and
275
- # the two ends of that range have to be in the clone. The range itself is narrow — see
276
- # "gitleaks detect" below (#716).
277
- fetch-depth: 0
278
- persist-credentials: false
279
-
280
- # Kept between jobs (#696) — GitHub-hosted only: a fresh VM has nothing on disk, so the
281
- # binary comes back from here and the install step below downloads nothing.
282
- # - Self-hosted → off. A persistent runner keeps its tool cache on disk already, and a
283
- # remote cache on top was measured as a loss, not a saving (#512).
284
- # - Keyed on the pin and the platform: a version bump is a miss. The post step saves
285
- # only when the job passes, so a failed download is never what gets cached.
286
- # A NEW step, skipped on self-hosted. "Install gitleaks (pinned release binary)" keeps
287
- # its name: handbook-sync recognises a copy of this job by it.
288
- # EDIT: self-hosted runners are already off; to turn it off everywhere, delete this step.
289
- - name: Restore gitleaks cache
290
- if: runner.environment == 'github-hosted'
291
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
292
- with:
293
- path: ${{ runner.tool_cache }}/gitleaks/${{ env.GITLEAKS_VERSION }}
294
- key: gitleaks-${{ env.GITLEAKS_VERSION }}-${{ runner.os }}-${{ runner.arch }}
295
-
296
- - name: Install gitleaks (pinned release binary)
297
- env:
298
- # Authenticated (#698). Under load GitHub sheds ANONYMOUS release downloads first:
299
- # measured 2026-11-09, ~90 min of instant 504s from github.com/…/releases/download,
300
- # while the API asset path below answered 200 with the same file. The job's own token
301
- # is enough — reading a public release needs an identity, not a permission.
302
- GH_TOKEN: ${{ github.token }}
303
- run: |
304
- # NOT gitleaks/gitleaks-action@v2 — it demands a paid GITLEAKS_LICENSE for
305
- # organization-owned repositories. The plain release binary is MIT.
306
- # Resolve OS/arch from uname — a hardcoded linux_x64 binary on a macOS
307
- # self-hosted runner cannot exec, and fails as a bare exit 126.
308
- case "$(uname -s)" in
309
- Darwin) os=darwin ;;
310
- Linux) os=linux ;;
311
- *) echo "unsupported OS: $(uname -s)" >&2; exit 1 ;;
312
- esac
313
- case "$(uname -m)" in
314
- arm64|aarch64) arch=arm64 ;;
315
- x86_64|amd64) arch=x64 ;;
316
- *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
317
- esac
318
- # Kept between jobs (#696): a pinned version is downloaded once per runner, not on
319
- # every run. A release download can answer 504 for hours (measured: 20 of 20 tries),
320
- # which outlasts any retry, so the binary has to be on the runner already.
321
- # Into the runner's tool cache, not /usr/local/bin: no sudo, no global write — the
322
- # per-runner directory setup-node and setup-python install into. A persistent
323
- # self-hosted runner keeps it on disk; a GitHub-hosted VM gets it back from the
324
- # "Restore gitleaks cache" step above. The version is in the path, so a pin bump is a
325
- # miss, never a stale binary. EDIT: an ephemeral self-hosted runner keeps neither and
326
- # downloads on every run.
327
- dir="${RUNNER_TOOL_CACHE:-$RUNNER_TEMP}/gitleaks/${GITLEAKS_VERSION}/${os}-${arch}"
328
- if [ -x "$dir/gitleaks" ]; then
329
- echo "gitleaks ${GITLEAKS_VERSION} already on this runner: $dir"
330
- else
331
- mkdir -p "$dir"
332
- tmp="$(mktemp -d "$dir.XXXXXX")"
333
- trap 'rm -rf "$tmp"' EXIT
334
- asset="gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
335
- sums="gitleaks_${GITLEAKS_VERSION}_checksums.txt"
336
- # fetch <accept> <url> <file> — every request of this step, one curl line.
337
- # --fail: on an HTTP error curl otherwise saves the error page and exits 0, and tar
338
- # then fails with "not in gzip format", naming neither the download nor the host.
339
- # --retry: a re-run during the same upstream error spends the one re-run branch CI
340
- # allows, so a brief error is retried here first. A longer outage still fails, at
341
- # curl, naming the status (#690).
342
- # The token reaches api.github.com only: curl drops an -H Authorization header when
343
- # the asset's 302 leads to another host, so the download CDN never sees it.
344
- fetch() {
345
- curl -fsSL --retry 5 --retry-delay 10 --retry-all-errors --connect-timeout 10 --max-time 120 \
346
- -H "Authorization: Bearer ${GH_TOKEN}" -H "Accept: $1" -o "$3" "$2"
347
- }
348
- # The API serves an asset by id, not by name, so look the ids up in the release. No jq:
349
- # a self-hosted runner need not have it. Splitting on , { [ leaves one key per line
350
- # whether the JSON comes pretty or compact; within an asset, "url" precedes "name". Were
351
- # that order ever to change, the wrong file would arrive and the sha256 check below
352
- # would refuse it — a loud failure, never a wrong binary.
353
- fetch application/vnd.github+json \
354
- "https://api.github.com/repos/gitleaks/gitleaks/releases/tags/v${GITLEAKS_VERSION}" "$tmp/release.json"
355
- for f in "$asset" "$sums"; do
356
- url="$(tr ',{[' '\n\n\n' < "$tmp/release.json" | awk -F'"' -v want="$f" '
357
- $2 == "url" && $4 ~ /\/releases\/assets\/[0-9]+$/ { u = $4 }
358
- $2 == "name" && $4 == want && !found { print u; found = 1 }')"
359
- if [ -z "$url" ]; then
360
- echo "::error::gitleaks release v${GITLEAKS_VERSION} has no asset $f"; exit 1
361
- fi
362
- fetch application/octet-stream "$url" "$tmp/$f"
363
- done
364
- # Verified before tar (#698): an error page, a truncated file or a wrong archive stops
365
- # here, naming the file, instead of reaching tar — or, for a valid archive, the PATH.
366
- want="$(awk -v f="$asset" '$2 == f { print $1 }' "$tmp/$sums")"
367
- if command -v sha256sum >/dev/null; then got="$(sha256sum "$tmp/$asset" | awk '{ print $1 }')"
368
- else got="$(shasum -a 256 "$tmp/$asset" | awk '{ print $1 }')"; fi # macOS self-hosted
369
- if [ -z "$want" ]; then
370
- echo "::error::$sums does not list $asset, so it cannot be verified"; exit 1
371
- fi
372
- if [ "$got" != "$want" ]; then
373
- echo "::error::sha256 mismatch for $asset: got $got, $sums lists $want"; exit 1
374
- fi
375
- tar -xzf "$tmp/$asset" -C "$tmp" gitleaks
376
- chmod +x "$tmp/gitleaks"
377
- # One rename on one filesystem: a job sharing this tool cache sees no binary or a
378
- # whole one, never half of one.
379
- mv -f "$tmp/gitleaks" "$dir/gitleaks"
380
- fi
381
- echo "$dir" >> "$GITHUB_PATH"
382
-
383
- # The scan range (#716): only the commits this run brings, never `git log --all`. A
384
- # fetch-depth-0 checkout holds every branch and tag, and gitleaks' default range is all of
385
- # them — so one unshipped branch's finding turned EVERY branch's run red, a trunk cure
386
- # included, until that branch rewrote its history.
387
- # - A branch push: the commits not yet on trunk (origin/<trunk>..HEAD).
388
- # - A trunk push: the pushed range (before..HEAD).
389
- # - No range to read (a dispatch, a first or forced trunk push, trunk not fetched): HEAD's
390
- # own history — still never another branch's.
391
- # Trunk is `trunk:` in .github/project.yml, else the repository's default branch. Every
392
- # commit trunk's tip can reach is scanned by the heavy lane instead (templates/
393
- # ci-<stack>-heavy.yml, job `secrets`), which blocks no merge. The step keeps its name.
394
- - name: gitleaks detect
395
- env:
396
- EVENT: ${{ github.event_name }}
397
- REF_NAME: ${{ github.ref_name }}
398
- BEFORE: ${{ github.event.before }}
399
- DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
400
- run: |
401
- trunk="$(sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" .github/project.yml 2>/dev/null | head -n 1 || true)"
402
- trunk="${trunk:-$DEFAULT_BRANCH}"
403
- commit() { [ -n "$1" ] && git rev-parse --verify -q "$1^{commit}" >/dev/null; }
404
- if [ -n "$trunk" ] && [ "$REF_NAME" = "$trunk" ]; then
405
- if [ "$EVENT" = push ] && commit "$BEFORE" && git merge-base --is-ancestor "$BEFORE" HEAD; then
406
- range="$BEFORE..HEAD"
407
- else
408
- range=HEAD
409
- fi
410
- elif [ -n "$trunk" ] && commit "refs/remotes/origin/$trunk"; then
411
- range="refs/remotes/origin/$trunk..HEAD"
412
- else
413
- range=HEAD
414
- fi
415
- echo "Secret scan range: $range ($(git rev-list --count "$range") commit(s))"
416
- gitleaks detect --source . --no-banner --log-opts="$range"
417
-
418
- build:
419
- name: Build (Laravel + Vite)
420
- needs: dedupe
421
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
422
- runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: full (quick if it keeps quick's promise) on a branch, trunk on trunk (CONVENTIONS.md §7, "Runner classes").
423
- timeout-minutes: 45 # a hung build must not hold the runner for the 360-minute default (#572).
424
- # EDIT: measured (#572): the slowest Laravel adopter's build ran p99 20 / max 26 min. Keep this
425
- # well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
426
- # Re-exported so the migrations job below resolves PHP exactly once, here.
427
- outputs:
428
- php-version: ${{ steps.toolchain.outputs.php-version }}
429
- steps:
430
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
431
- with:
432
- persist-credentials: false
433
-
434
- # Decide the test tier (#512). Not an `env:` expression, because the answer depends on
435
- # the repo's trunk (.github/project.yml), which only exists once the tree is checked out.
436
- # RUN_TESTS 'true' / 'false' → used as written.
437
- # 'auto', a pull_request run → on when the PR targets main (copies that restore PRs).
438
- # 'auto', push or dispatch → on for main, and for every branch when trunk is main
439
- # (Tier B); off for a dev trunk and its branches (Tier C).
440
- - name: Decide the test tier
441
- id: tier
442
- env:
443
- DECLARED: ${{ env.RUN_TESTS }}
444
- EVENT: ${{ github.event_name }}
445
- REF: ${{ github.ref }}
446
- BASE_REF: ${{ github.base_ref }}
447
- DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
448
- run: |
449
- case "$DECLARED" in
450
- true|false) run="$DECLARED" ;;
451
- *)
452
- trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
453
- [ -n "$trunk" ] || trunk="$DEFAULT_BRANCH"
454
- if [ "$EVENT" = "pull_request" ]; then
455
- [ "$BASE_REF" = "main" ] && run=true || run=false
456
- elif [ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]; then
457
- run=true
458
- else
459
- run=false
460
- fi ;;
461
- esac
462
- echo "run_tests=$run" >> "$GITHUB_OUTPUT"
463
- echo "::notice::Pest suite: $run (RUN_TESTS=$DECLARED, event=$EVENT, ref=$REF)"
464
-
465
- # ---------------------------------------------------------------------------
466
- # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
467
- # it fails closed to the safe default, silently. `ship-batch: 5` (the cap was 3)
468
- # once turned every landing in a busy repo back to serial while this CI stayed
469
- # green; only a ship dry run noticed. So the value fails HERE, where the person
470
- # who changed project.yml is looking. Same rule as `colab ship` and the audit
471
- # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–8. Why the
472
- # cap is 8: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
473
- # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
474
- # `ship-batch-steps` (#557, parseShipBatchSteps): absent/empty/null, or ascending
475
- # whole numbers within ship-batch — 2,4,8 or [2, 4, 8].
476
- # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
477
- # ---------------------------------------------------------------------------
478
- - name: Descriptor check (.github/project.yml)
479
- working-directory: ${{ github.workspace }}
480
- run: |
481
- [ -f .github/project.yml ] || exit 0
482
- # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
483
- field() {
484
- grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
485
- | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
486
- -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
487
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
488
- }
489
- v="$(field ship-batch)"
490
- case "$v" in
491
- ''|'~'|null|1|2|3|4|5|6|7|8) echo "ship-batch: ${v:-absent} — ok" ;;
492
- *)
493
- 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."
494
- exit 1 ;;
495
- esac
496
- # ship-batch-steps (#557): ascending whole numbers, each within ship-batch (the ceiling read above).
497
- s="$(field ship-batch-steps)"
498
- case "$s" in
499
- ''|'~'|null) echo "ship-batch-steps: absent — ok (fixed size)" ;;
500
- *)
501
- case "$v" in ''|'~'|null) ceil=1 ;; *) ceil="$v" ;; esac
502
- list="$(printf '%s' "$s" | sed -E -e 's/^\[(.*)\]$/\1/' -e 's/^[[:space:]]+//' -e 's/[[:space:]]+$//' -e 's/[[:space:]]*,[[:space:]]*/,/g')"
503
- if printf '%s\n' "$list" | grep -Eq '^[1-9][0-9]*(,[1-9][0-9]*)*$' \
504
- && 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
505
- echo "ship-batch-steps: $list — ok"
506
- else
507
- 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."
508
- exit 1
509
- fi ;;
510
- esac
511
- # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
512
- w="$(field ship-batch-wait)"
513
- case "$w" in
514
- ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
515
- *)
516
- if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
517
- echo "ship-batch-wait: $w — ok"
518
- else
519
- 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."
520
- exit 1
521
- fi ;;
522
- esac
523
- # ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
524
- # Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
525
- f="$(field ci-wait-factor)"
526
- case "$f" in
527
- ''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
528
- *)
529
- if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
530
- echo "ci-wait-factor: $f — ok"
531
- else
532
- 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."
533
- exit 1
534
- fi ;;
535
- esac
536
- # thresholds (#560): one level of `name: whole number`, each name known and at or above its
537
- # floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
538
- # which a test holds this list to.
539
- # A bad entry falls back to the default everywhere, silently, so it fails here.
540
- bad=0
541
- while IFS= read -r t; do
542
- case "$t" in =*)
543
- echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
544
- bad=1; continue ;;
545
- esac
546
- k="${t%%:*}"
547
- n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
548
- max=999999999
549
- case "$k" in
550
- hot-file-count|claude-md-line-multiple) min=2 ;;
551
- dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
552
- claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
553
- batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
554
- *) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
555
- bad=1; continue ;;
556
- esac
557
- case "$n" in ''|'~'|null) continue ;; esac
558
- if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
559
- echo "thresholds.$k: $n — ok"
560
- else
561
- 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."
562
- bad=1
563
- fi
564
- done < <(awk '
565
- /^thresholds[[:space:]]*:/ { b = 1; v = $0
566
- sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
567
- if (v != "" && v != "~" && v != "null") print "=" v
568
- next }
569
- b && /^[[:space:]]*(#|$)/ { next }
570
- b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
571
- { b = 0 }' .github/project.yml)
572
- [ "$bad" = 0 ] || exit 1
573
-
574
- # ---------------------------------------------------------------------------
575
- # Toolchain resolution. Precedence, highest first:
576
- # PHP : 1. .github/project.yml -> php: 2. composer.json -> require.php
577
- # Node: 1. .github/project.yml -> node: 2. .nvmrc, else package.json engines.node
578
- # ...and if neither declares it, FAIL.
579
- #
580
- # There is deliberately NO fallback default. A silent default is exactly how a
581
- # repo here ended up building on Node 20 in CI while deploying on Node 22 —
582
- # CI was green and proved nothing about what actually shipped. Keep these equal
583
- # to what the deploy target runs, or CI proves nothing.
584
- # ---------------------------------------------------------------------------
585
- - name: Resolve toolchain versions
586
- id: toolchain
587
- run: |
588
- set -euo pipefail
589
-
590
- # "^8.3" / ">=22.1" / "v22" / "8.4.*" -> "8.3" / "22.1" / "22" / "8.4"
591
- normalise() {
592
- printf '%s' "$1" \
593
- | tr -d '"' \
594
- | sed -E 's/^[^0-9]*//' \
595
- | sed -E 's/[[:space:]].*$//' \
596
- | sed -E 's/\.(x|\*)$//' \
597
- | sed -E 's/[^0-9.].*$//' \
598
- | sed -E 's/\.$//'
599
- }
600
-
601
- # Read a flat `key: value` out of .github/project.yml. That file is a
602
- # handful of top-level keys by design, so this is sufficient.
603
- from_project_yml() {
604
- [ -f .github/project.yml ] || return 0
605
- sed -nE "s/^[[:space:]]*$1:[[:space:]]*\"?([^\"#[:space:]]+)\"?.*/\1/p" .github/project.yml | head -1
606
- }
607
-
608
- # --- PHP ---------------------------------------------------------------
609
- PHP_VERSION=""; PHP_SOURCE=""
610
- V="$(from_project_yml php || true)"
611
- if [ -n "$V" ] && [ "$V" != "null" ]; then
612
- PHP_VERSION="$(normalise "$V")"; PHP_SOURCE=".github/project.yml (php:)"
613
- fi
614
- if [ -z "$PHP_VERSION" ] && [ -f composer.json ]; then
615
- V=""
616
- if command -v php >/dev/null 2>&1; then
617
- V="$(php -r '$c=json_decode(file_get_contents("composer.json"),true); echo $c["require"]["php"] ?? "";' || true)"
618
- elif command -v python3 >/dev/null 2>&1; then
619
- V="$(python3 -c "import json;print((json.load(open('composer.json')).get('require') or {}).get('php') or '')" || true)"
620
- elif command -v node >/dev/null 2>&1; then
621
- V="$(node -e "try{const r=require('./composer.json').require||{};process.stdout.write(String(r.php||''))}catch(_){}" || true)"
622
- fi
623
- if [ -n "$V" ]; then
624
- PHP_VERSION="$(normalise "$V")"; PHP_SOURCE="composer.json (require.php)"
625
- fi
626
- fi
627
- if [ -z "$PHP_VERSION" ]; then
628
- echo "::error::No PHP version is declared in this repository, and this workflow refuses to guess one."
629
- {
630
- echo "Declare it in ONE of:"
631
- echo " 1. .github/project.yml -> php: \"8.4\" (preferred)"
632
- echo " 2. composer.json -> \"require\": { \"php\": \"^8.4\" }"
633
- echo "Use the version the DEPLOY target runs."
634
- } >&2
635
- exit 1
636
- fi
637
-
638
- # --- Node --------------------------------------------------------------
639
- NODE_VERSION=""; NODE_SOURCE=""
640
- V="$(from_project_yml node || true)"
641
- if [ -n "$V" ] && [ "$V" != "null" ]; then
642
- NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".github/project.yml (node:)"
643
- fi
644
- if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
645
- V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
646
- if [ -n "$V" ]; then
647
- NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".nvmrc"
648
- fi
649
- fi
650
- if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
651
- V=""
652
- if command -v node >/dev/null 2>&1; then
653
- V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
654
- elif command -v python3 >/dev/null 2>&1; then
655
- V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
656
- fi
657
- if [ -n "$V" ]; then
658
- NODE_VERSION="$(normalise "$V")"; NODE_SOURCE="package.json (engines.node)"
659
- fi
660
- fi
661
- if [ -z "$NODE_VERSION" ]; then
662
- echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
663
- {
664
- echo "Declare it in ONE of:"
665
- echo " 1. .github/project.yml -> node: \"22\" (preferred)"
666
- echo " 2. .nvmrc -> 22 or package.json -> \"engines\": { \"node\": \">=22\" }"
667
- echo "Use the version the DEPLOY target runs."
668
- } >&2
669
- exit 1
670
- fi
671
-
672
- echo "php-version=$PHP_VERSION" >> "$GITHUB_OUTPUT"
673
- echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
674
- echo "PHP $PHP_VERSION (from: $PHP_SOURCE) / Node $NODE_VERSION (from: $NODE_SOURCE)"
675
- {
676
- echo "PHP **$PHP_VERSION** — resolved from \`$PHP_SOURCE\`"
677
- echo ""
678
- echo "Node **$NODE_VERSION** — resolved from \`$NODE_SOURCE\`"
679
- } >> "$GITHUB_STEP_SUMMARY"
680
-
681
- - name: Setup PHP
682
- uses: shivammathur/setup-php@v2
683
- with:
684
- php-version: ${{ steps.toolchain.outputs.php-version }}
685
- # sqlite3 + pdo_sqlite are what the throwaway bootstrap below runs on.
686
- extensions: mbstring, sqlite3, pdo_sqlite, bcmath, intl # EDIT: add what this app needs.
687
- coverage: none
688
-
689
- # Package cache (#571): Composer's download cache, on only on a GitHub-hosted runner AND
690
- # with composer.lock present. Both halves are load-bearing:
691
- # - No composer.lock → nothing stable to key on; every run would save a fresh entry.
692
- # - Self-hosted → off. A persistent runner already keeps Composer's cache dir between
693
- # jobs; a remote cache on top was measured as a loss, not a saving (#512).
694
- # Two NEW steps, both skipped where the gate is off. "Composer install" keeps its name
695
- # and its body: `colab ship`'s cure rule matches steps by exact name.
696
- # EDIT: self-hosted runners are already off; to turn caching off everywhere, delete these
697
- # two steps.
698
- - name: Locate Composer cache
699
- id: composer-cache
700
- if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
701
- run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
702
-
703
- - name: Restore Composer cache
704
- if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
705
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
706
- with:
707
- path: ${{ steps.composer-cache.outputs.dir }}
708
- key: composer-${{ runner.os }}-${{ hashFiles('composer.lock') }}
709
- restore-keys: composer-${{ runner.os }}-
710
-
711
- - name: Composer install
712
- env:
713
- RUN_TESTS: ${{ steps.tier.outputs.run_tests }}
714
- run: |
715
- # --no-scripts: the post-autoload-dump hook runs `package:discover`, which
716
- # boots the app — and the app cannot boot until the .env below exists.
717
- # Dev dependencies are installed only when the Pest suite will run; a build-
718
- # only job does not need them (wayfinder lives in require, not require-dev).
719
- if [ "$RUN_TESTS" = "true" ]; then
720
- composer install --no-interaction --prefer-dist --optimize-autoloader --no-scripts
721
- else
722
- composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader --no-scripts
723
- fi
724
-
725
- - name: Prepare throwaway env for build-time codegen (wayfinder)
726
- run: |
727
- # See the header: .env.example ships DB_CONNECTION=mysql, but there is no
728
- # MySQL on the runner. Rewrite to sqlite against an empty file so artisan
729
- # boots. This .env is disposable — deploy workflows rsync with --exclude
730
- # '.env', so it can never reach a server.
731
- cp .env.example .env
732
- sed -i 's/^DB_CONNECTION=.*/DB_CONNECTION=sqlite/' .env
733
- touch database/database.sqlite
734
- php artisan key:generate --force
735
- php artisan package:discover --ansi
736
-
737
- echo "=== PHP version on runner ==="
738
- php -v
739
-
740
- echo "=== wayfinder:generate (stderr visible) ==="
741
- # Run it here rather than letting the Vite plugin invoke it: the plugin hides
742
- # stderr and reports only "Command failed".
743
- php artisan wayfinder:generate $WAYFINDER_ARGS
744
-
745
- # npm cache (#571): the same gate as the Composer cache above — GitHub-hosted AND
746
- # package-lock.json present (`cache: npm` fails the step without one). The automatic
747
- # `packageManager` cache is pinned to the same condition so it cannot override it.
748
- # EDIT: to turn it off everywhere, replace both expressions with '' and false.
749
- - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
750
- with:
751
- node-version: ${{ steps.toolchain.outputs.node-version }}
752
- cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
753
- package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
754
-
755
- - name: Build frontend assets (Vite)
756
- run: |
757
- npm ci
758
- npm run build
759
-
760
- - name: Run migrations against sqlite
761
- if: steps.tier.outputs.run_tests == 'true'
762
- run: |
763
- # Migrations must apply cleanly from zero. This is the cheapest way to catch
764
- # a migration that only works against an already-populated database.
159
+ run=false
160
+ fi ;;
161
+ esac
162
+ echo "::notice::Pest suite: $run (RUN_TESTS=$RUN_TESTS, event=$EVENT, ref=$REF)"
163
+ # ── end of the test tier
164
+
165
+ # --no-scripts: the post-autoload-dump hook runs `package:discover`, which boots the app —
166
+ # and the app cannot boot until the .env below exists. Dev dependencies only when the Pest
167
+ # suite will run; a build-only job does not need them (wayfinder lives in require).
168
+ if [ "$run" = true ]; then
169
+ composer install --no-interaction --prefer-dist --optimize-autoloader --no-scripts
170
+ else
171
+ composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader --no-scripts
172
+ fi
173
+
174
+ # The throwaway env (see the header): .env.example ships DB_CONNECTION=mysql, but there is
175
+ # no MySQL on the runner. Rewrite to sqlite against an empty file so artisan boots. This .env
176
+ # is disposable — deploy workflows rsync with --exclude '.env', so it never reaches a server.
177
+ cp .env.example .env
178
+ sed -i 's/^DB_CONNECTION=.*/DB_CONNECTION=sqlite/' .env
179
+ touch database/database.sqlite
180
+ php artisan key:generate --force
181
+ php artisan package:discover --ansi
182
+ php -v
183
+ # Run it here rather than letting the Vite plugin invoke it: the plugin hides stderr and
184
+ # reports only "Command failed".
185
+ echo "=== wayfinder:generate (stderr visible) ==="
186
+ # shellcheck disable=SC2086
187
+ php artisan wayfinder:generate $WAYFINDER_ARGS
188
+
189
+ npm ci
190
+ npm run build
191
+
192
+ if [ "$run" = true ]; then
193
+ # Migrations must apply cleanly from zero — the cheapest catch for a migration that only
194
+ # works against an already-populated database.
765
195
  php artisan migrate --force
766
-
767
- - name: Test (Pest)
768
- if: steps.tier.outputs.run_tests == 'true'
769
- run: |
770
196
  if [ -f vendor/bin/pest ]; then
771
197
  vendor/bin/pest --ci --exclude-group=heavy # light lane; ci-heavy.yml runs the full suite
772
198
  elif [ -f vendor/bin/phpunit ]; then
773
199
  echo "::notice::No Pest binary — falling back to PHPUnit."
774
200
  vendor/bin/phpunit --exclude-group=heavy
775
201
  else
776
- echo "::error::RUN_TESTS is true but neither vendor/bin/pest nor vendor/bin/phpunit exists. Add a test runner, or set RUN_TESTS: false."
202
+ echo "::error::RUN_TESTS is true but neither vendor/bin/pest nor vendor/bin/phpunit exists. Add a test runner, or set RUN_TESTS=false."
777
203
  exit 1
778
204
  fi
205
+ fi
206
+ # EDIT: measured (#572): the slowest Laravel adopter's build ran p99 20 / max 26 min. Keep this
207
+ # well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
208
+ full-timeout-minutes: 45
209
+ #
210
+ # EDIT: self-hosted runners — `classes` runs each job on ["self-hosted", <class>]: `trunk` on a
211
+ # trunk ref, else `quick` or `full` (CONVENTIONS.md §7, "Runner classes"). A public repo keeps
212
+ # the default, ubuntu-latest. A bare label or a JSON label list also works.
213
+ # runs-on: classes
214
+ # runner-lane: my-repo-lane # only for a capped lane (rule 3)
215
+ #
216
+ # EDIT: name your trunk-only jobs below (deploy, publish) when they sit outside the gate (#717).
217
+ # trunk-only-jobs: Deploy
218
+ #
219
+ # EDIT: bump deliberately, not automatically.
220
+ # gitleaks-version: "8.30.1"
221
+
222
+ # Your own jobs go here, beside the call. Behind the gate (they skip when the tree already passed):
223
+ # needs: ci
224
+ # if: ${{ !cancelled() && needs.ci.result == 'success' && needs.ci.outputs.tested != 'true' }}
225
+ # Trunk-only and ungated: no `if:` on the guard, and list the job's name in `trunk-only-jobs` above.
779
226
 
780
227
  # ---------------------------------------------------------------------------
781
228
  # Migration round-trip — see the header for what each engine catches.
@@ -802,11 +249,10 @@ jobs:
802
249
  # ---------------------------------------------------------------------------
803
250
  migrations:
804
251
  name: Migration round-trip (${{ matrix.engine }})
805
- needs: build
806
- # Explicit result check, not the implicit success(): success() reads EVERY ancestor,
807
- # including `dedupe`, which is skipped on every ordinary push — so the implicit
808
- # form would skip this job on exactly the runs it exists for (#418).
809
- if: ${{ !cancelled() && needs.build.result == 'success' }}
252
+ needs: ci
253
+ # Behind the gate: runs where the call tested this tree, skips where the gate reused a green
254
+ # run of it. An explicit result check, not the implicit success() (#418).
255
+ if: ${{ !cancelled() && needs.ci.result == 'success' && needs.ci.outputs.tested != 'true' }}
810
256
  runs-on: ubuntu-latest # EDIT: self-hosted → a class, never a host: e2e (service containers) (CONVENTIONS.md §7, "Runner classes").
811
257
  timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
812
258
  # EDIT: measured (#572): p99 under 4 min / max 5 min on every adopter. Keep it well above your own p99.
@@ -867,7 +313,7 @@ jobs:
867
313
  - name: Setup PHP
868
314
  uses: shivammathur/setup-php@v2
869
315
  with:
870
- php-version: ${{ needs.build.outputs.php-version }}
316
+ php-version: ${{ needs.ci.outputs.php-version }}
871
317
  extensions: mbstring, sqlite3, pdo_sqlite, pdo_mysql, bcmath, intl # EDIT: add what this app needs.
872
318
  coverage: none
873
319