@futurelastic/colab-handbook 1.13.0-rc.35 → 1.13.0-rc.37

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/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.35"
36
+ "version": "1.13.0-rc.37"
37
37
  }
@@ -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.** On a repo whose trunk has another
71
- name, edit both. Until you do, the guard simply never fires on trunk — nothing breaks.
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*.
@@ -67,31 +67,40 @@ 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
- # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
72
- # trunk, main the release; Tier B: main only).
73
- branches: [main, dev]
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").
74
77
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
75
78
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
76
79
  workflow_dispatch:
77
80
 
78
81
  # One live run per branch: a new push cancels the superseded run on the same ref.
79
82
  # 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"). Pull-request runs
81
- # group under refs/pull/<n>/merge, apart from the branch's push runs.
82
- # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
83
- # may carry any name; one left off this list gets its trunk runs cancelled.
83
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
84
+ # group of its own (the run id): GitHub cancels an older run that is still PENDING in a
85
+ # group even when cancel-in-progress is false, so a third quick merge would otherwise
86
+ # drop the second one's run before it ever started (#512).
87
+ # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
88
+ # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
89
+ # name; one left off this list gets its trunk runs cancelled.
84
90
  concurrency:
85
- group: ci-${{ github.ref }}
91
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
86
92
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
87
93
 
88
94
  env:
89
- # Light CI on the dev trunk (does it build at all, ~2 min); heavy CI on main, where
90
- # the Pest suite gates a release. On Tier C main IS production — promotion is the
91
- # deploy — so this suite is the last gate before users, not a release formality.
92
- # EDIT: set to a literal 'true' if this repo is Tier B (main is trunk) and you
93
- # always want the suite.
94
- RUN_TESTS: ${{ github.ref == 'refs/heads/main' || github.base_ref == 'main' }}
95
+ # Whether the Pest suite runs. 'auto' is decided by the "Decide the test tier" step in
96
+ # `build` (#512). Light CI on a dev trunk and its branches (does it build at all,
97
+ # ~2 min); heavy CI on main, where the Pest suite gates a release. On Tier C main IS
98
+ # production — promotion is the deploy — so this suite is the last gate before users,
99
+ # not a release formality. When main is the trunk (Tier B) every branch push runs the
100
+ # suite too: this workflow has no `pull_request` run any more, and that run used to be
101
+ # the only place a Tier B branch got its tests.
102
+ # EDIT: set to a literal 'true' to always run the suite, 'false' to never run it.
103
+ RUN_TESTS: auto
95
104
  # EDIT: bump deliberately, not automatically.
96
105
  GITLEAKS_VERSION: "8.30.1"
97
106
  # EDIT: match the app's APP_NAME. Leave empty if the build does not read it.
@@ -139,6 +148,7 @@ jobs:
139
148
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
140
149
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
141
150
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
151
+ timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
142
152
  permissions:
143
153
  actions: read
144
154
  contents: read
@@ -207,6 +217,7 @@ jobs:
207
217
  needs: dedupe
208
218
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
209
219
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
220
+ timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
210
221
  steps:
211
222
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
212
223
  with:
@@ -256,6 +267,37 @@ jobs:
256
267
  with:
257
268
  persist-credentials: false
258
269
 
270
+ # Decide the test tier (#512). Not an `env:` expression, because the answer depends on
271
+ # the repo's trunk (.github/project.yml), which only exists once the tree is checked out.
272
+ # RUN_TESTS 'true' / 'false' → used as written.
273
+ # 'auto', a pull_request run → on when the PR targets main (copies that restore PRs).
274
+ # 'auto', push or dispatch → on for main, and for every branch when trunk is main
275
+ # (Tier B); off for a dev trunk and its branches (Tier C).
276
+ - name: Decide the test tier
277
+ id: tier
278
+ env:
279
+ DECLARED: ${{ env.RUN_TESTS }}
280
+ EVENT: ${{ github.event_name }}
281
+ REF: ${{ github.ref }}
282
+ BASE_REF: ${{ github.base_ref }}
283
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
284
+ run: |
285
+ case "$DECLARED" in
286
+ true|false) run="$DECLARED" ;;
287
+ *)
288
+ trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
289
+ [ -n "$trunk" ] || trunk="$DEFAULT_BRANCH"
290
+ if [ "$EVENT" = "pull_request" ]; then
291
+ [ "$BASE_REF" = "main" ] && run=true || run=false
292
+ elif [ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]; then
293
+ run=true
294
+ else
295
+ run=false
296
+ fi ;;
297
+ esac
298
+ echo "run_tests=$run" >> "$GITHUB_OUTPUT"
299
+ echo "::notice::Pest suite: $run (RUN_TESTS=$DECLARED, event=$EVENT, ref=$REF)"
300
+
259
301
  # ---------------------------------------------------------------------------
260
302
  # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
261
303
  # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
@@ -464,6 +506,8 @@ jobs:
464
506
  coverage: none
465
507
 
466
508
  - name: Composer install
509
+ env:
510
+ RUN_TESTS: ${{ steps.tier.outputs.run_tests }}
467
511
  run: |
468
512
  # --no-scripts: the post-autoload-dump hook runs `package:discover`, which
469
513
  # boots the app — and the app cannot boot until the .env below exists.
@@ -505,14 +549,14 @@ jobs:
505
549
  npm run build
506
550
 
507
551
  - name: Run migrations against sqlite
508
- if: env.RUN_TESTS == 'true'
552
+ if: steps.tier.outputs.run_tests == 'true'
509
553
  run: |
510
554
  # Migrations must apply cleanly from zero. This is the cheapest way to catch
511
555
  # a migration that only works against an already-populated database.
512
556
  php artisan migrate --force
513
557
 
514
558
  - name: Test (Pest)
515
- if: env.RUN_TESTS == 'true'
559
+ if: steps.tier.outputs.run_tests == 'true'
516
560
  run: |
517
561
  if [ -f vendor/bin/pest ]; then
518
562
  vendor/bin/pest --ci
@@ -41,22 +41,28 @@ on:
41
41
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
42
42
  # merge into, and nothing looks broken (CONVENTIONS.md §7).
43
43
  branches: ['**']
44
- pull_request:
45
- # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
46
- # trunk, main the release; Tier B: main only).
47
- branches: [main, dev]
44
+ # No `pull_request:` here (#512). A branch with an open PR in this repository already
45
+ # has a push run at the same head, and a `pull_request` run beside it doubled the CI
46
+ # per commit while testing a merge ref instead of the sha that lands. Readers keep only
47
+ # the newest run per workflow at a sha, so that second run also decided the verdict.
48
+ # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
49
+ # has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
50
+ # only branch run (CONVENTIONS.md §4, "Branch CI").
48
51
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
49
52
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
50
53
  workflow_dispatch:
51
54
 
52
55
  # One live run per branch: a new push cancels the superseded run on the same ref.
53
56
  # Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
54
- # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
55
- # group under refs/pull/<n>/merge, apart from the branch's push runs.
56
- # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
57
- # may carry any name; one left off this list gets its trunk runs cancelled.
57
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
58
+ # group of its own (the run id): GitHub cancels an older run that is still PENDING in a
59
+ # group even when cancel-in-progress is false, so a third quick merge would otherwise
60
+ # drop the second one's run before it ever started (#512).
61
+ # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
62
+ # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
63
+ # name; one left off this list gets its trunk runs cancelled.
58
64
  concurrency:
59
- group: ci-${{ github.ref }}
65
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
60
66
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
61
67
 
62
68
  env:
@@ -105,6 +111,7 @@ jobs:
105
111
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
106
112
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
107
113
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
114
+ timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
108
115
  permissions:
109
116
  actions: read
110
117
  contents: read
@@ -173,6 +180,7 @@ jobs:
173
180
  needs: dedupe
174
181
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
175
182
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
183
+ timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
176
184
  steps:
177
185
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
178
186
  with:
@@ -55,22 +55,28 @@ on:
55
55
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
56
56
  # merge into, and nothing looks broken (CONVENTIONS.md §7).
57
57
  branches: ['**']
58
- pull_request:
59
- # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
60
- # trunk, main the release; Tier B: main only).
61
- branches: [main, dev]
58
+ # No `pull_request:` here (#512). A branch with an open PR in this repository already
59
+ # has a push run at the same head, and a `pull_request` run beside it doubled the CI
60
+ # per commit while testing a merge ref instead of the sha that lands. Readers keep only
61
+ # the newest run per workflow at a sha, so that second run also decided the verdict.
62
+ # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
63
+ # has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
64
+ # only branch run (CONVENTIONS.md §4, "Branch CI").
62
65
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
63
66
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
64
67
  workflow_dispatch:
65
68
 
66
69
  # One live run per branch: a new push cancels the superseded run on the same ref.
67
70
  # Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
68
- # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
69
- # group under refs/pull/<n>/merge, apart from the branch's push runs.
70
- # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
71
- # may carry any name; one left off this list gets its trunk runs cancelled.
71
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
72
+ # group of its own (the run id): GitHub cancels an older run that is still PENDING in a
73
+ # group even when cancel-in-progress is false, so a third quick merge would otherwise
74
+ # drop the second one's run before it ever started (#512).
75
+ # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
76
+ # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
77
+ # name; one left off this list gets its trunk runs cancelled.
72
78
  concurrency:
73
- group: ci-${{ github.ref }}
79
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
74
80
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
75
81
 
76
82
  env:
@@ -119,6 +125,7 @@ jobs:
119
125
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
120
126
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
121
127
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
128
+ timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
122
129
  permissions:
123
130
  actions: read
124
131
  contents: read
@@ -187,6 +194,7 @@ jobs:
187
194
  needs: dedupe
188
195
  if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
189
196
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
197
+ timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
190
198
  steps:
191
199
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
192
200
  with:
@@ -103,6 +103,11 @@ on:
103
103
  # EDIT: only if your tag convention differs. This trigger is what makes
104
104
  # `deploy: tag` true — a tag is the deploy, a branch push is not.
105
105
  - "v*.*.*"
106
+ # A pre-release (v1.2.3-rc.1, -beta.2) never deploys: `v*.*.*` matches it, and the
107
+ # release workflow cuts a candidate tag automatically. The final tag is the deploy.
108
+ # This line MUST come right after the positive pattern it excludes — GitHub applies
109
+ # the patterns in order, so a negative pattern placed before it excludes nothing.
110
+ - "!v*.*.*-*"
106
111
  workflow_dispatch:
107
112
  inputs:
108
113
  ref: