@futurelastic/colab-handbook 1.12.0-rc.15 → 1.12.0-rc.16

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
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.15"
30
+ "version": "1.12.0-rc.16"
31
31
  }
@@ -31,6 +31,25 @@ Starting points you **copy into your own repo**. That is the entire model.
31
31
  | `docs-lint.yml` | `.github/workflows/docs-lint.yml` | Every repo that copied `docs-lint.mjs` | Advisory job — `continue-on-error: true` on the lint step, so a finding never blocks a merge until a repo deliberately removes that line. Requires `docs-lint.mjs` to already be in the repo; does not vendor it. |
32
32
  | `branch-name.yml` | `.github/workflows/branch-name.yml` | Opt-in — any repo that wants §4's branch shape checked on every PR | One step, no dependencies: the PR's head branch against CONVENTIONS.md §4's regex, both shapes (`<type>/<slug>-<N>` and the `<login>/<machine>/` prefixed one) passing as shipped. Once the repo declares `branchPrefix: machine`, delete the `?` after the regex's first group to require the prefix. The head ref reaches the script through `env:`, never interpolated — on a public repo it is attacker-chosen. |
33
33
 
34
+ ### The `dedupe` job — why a claimed branch's first run skips the suite (#418)
35
+
36
+ All three CI templates open with a `dedupe` job. It runs only on the push that **creates** a
37
+ ref, which is what a session claim does: it pushes the new branch at trunk's head. It checks
38
+ nothing out, needs `permissions: actions: read`, and asks whether this same workflow already
39
+ has a green, non-pull-request run at this exact sha. If one exists, every other job is
40
+ skipped and the run still concludes `success`. If not, or if the check cannot run, the suite
41
+ runs as before. Every later push skips the guard, so real commits always get the full suite.
42
+ Two things to keep in a copy:
43
+
44
+ - **The guard calls `gh`.** GitHub-hosted images have it. On a self-hosted image without
45
+ `gh`, the guard prints a notice and the suite runs, so nothing breaks, but nothing is saved
46
+ either.
47
+ - **Every other job needs `!cancelled()` in its `if:`.** Without it, a job inherits the
48
+ implicit `success()`, which reads every ancestor, `dedupe` included. A job that only needs
49
+ `dedupe` indirectly would then be skipped on every ordinary push. That is why the Laravel
50
+ `migrations` job checks `needs.build.result == 'success'` explicitly. Add the same pair of
51
+ conditions to any job you add.
52
+
34
53
  ### Migration round-trip — what the Laravel job proves, and what it cannot
35
54
 
36
55
  `ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
@@ -104,8 +104,59 @@ env:
104
104
  # jobs from different runs interleave, and trunk can wait behind branch runs.
105
105
  # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
106
106
  jobs:
107
+ # Already tested at this sha? (#418) — the claim push.
108
+ # A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
109
+ # claim record), so the branch's first push sits on a sha trunk has usually already
110
+ # run. Without this job that push re-runs the whole suite on a tested commit (~19% of
111
+ # all runs, measured across five adopting repos). This job runs ONLY on a ref's first
112
+ # push (`github.event.created`), checks nothing out, and asks one question: does THIS
113
+ # workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
114
+ # other job is skipped and the run concludes `success` — a branch-CI `green` that is
115
+ # true, because the same workflow passed at the same sha. Anything else — trunk still
116
+ # running, red, never run, `gh` missing, the API failing — and the suite runs as
117
+ # before (fail-open: this job never fails the run). Every later push has
118
+ # `created == false`, so a real commit always gets the full suite, with no extra hop.
119
+ # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
120
+ # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
121
+ # §4, "Branch CI"). This job is the one that ends green.
122
+ dedupe:
123
+ name: Already tested at this sha?
124
+ if: github.event_name == 'push' && github.event.created
125
+ runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
126
+ permissions:
127
+ actions: read
128
+ outputs:
129
+ tested: ${{ steps.check.outputs.tested }}
130
+ steps:
131
+ - name: Look for a green run of this workflow at this sha
132
+ id: check
133
+ env:
134
+ GH_TOKEN: ${{ github.token }}
135
+ REPO: ${{ github.repository }}
136
+ RUN_ID: ${{ github.run_id }}
137
+ SHA: ${{ github.sha }}
138
+ run: |
139
+ tested=false
140
+ if ! command -v gh >/dev/null 2>&1; then
141
+ echo "::notice::gh is not installed on this runner — running the full suite (#418)."
142
+ elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
143
+ echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
144
+ elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
145
+ --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
146
+ echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
147
+ elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
148
+ tested=true
149
+ echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
150
+ echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
151
+ else
152
+ echo "No green run of this workflow at $SHA yet — running the full suite."
153
+ fi
154
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
155
+
107
156
  gitleaks:
108
157
  name: Secret scan (gitleaks)
158
+ needs: dedupe
159
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
109
160
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
110
161
  steps:
111
162
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -145,6 +196,8 @@ jobs:
145
196
 
146
197
  build:
147
198
  name: Build (Laravel + Vite)
199
+ needs: dedupe
200
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
148
201
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
149
202
  # Re-exported so the migrations job below resolves PHP exactly once, here.
150
203
  outputs:
@@ -376,6 +429,10 @@ jobs:
376
429
  migrations:
377
430
  name: Migration round-trip (${{ matrix.engine }})
378
431
  needs: build
432
+ # Explicit result check, not the implicit success(): success() reads EVERY ancestor,
433
+ # including `dedupe`, which is skipped on every ordinary push — so the implicit
434
+ # form would skip this job on exactly the runs it exists for (#418).
435
+ if: ${{ !cancelled() && needs.build.result == 'success' }}
379
436
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
380
437
  strategy:
381
438
  fail-fast: false
@@ -69,8 +69,59 @@ env:
69
69
  # jobs from different runs interleave, and trunk can wait behind branch runs.
70
70
  # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
71
71
  jobs:
72
+ # Already tested at this sha? (#418) — the claim push.
73
+ # A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
74
+ # claim record), so the branch's first push sits on a sha trunk has usually already
75
+ # run. Without this job that push re-runs the whole suite on a tested commit (~19% of
76
+ # all runs, measured across five adopting repos). This job runs ONLY on a ref's first
77
+ # push (`github.event.created`), checks nothing out, and asks one question: does THIS
78
+ # workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
79
+ # other job is skipped and the run concludes `success` — a branch-CI `green` that is
80
+ # true, because the same workflow passed at the same sha. Anything else — trunk still
81
+ # running, red, never run, `gh` missing, the API failing — and the suite runs as
82
+ # before (fail-open: this job never fails the run). Every later push has
83
+ # `created == false`, so a real commit always gets the full suite, with no extra hop.
84
+ # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
85
+ # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
86
+ # §4, "Branch CI"). This job is the one that ends green.
87
+ dedupe:
88
+ name: Already tested at this sha?
89
+ if: github.event_name == 'push' && github.event.created
90
+ runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
91
+ permissions:
92
+ actions: read
93
+ outputs:
94
+ tested: ${{ steps.check.outputs.tested }}
95
+ steps:
96
+ - name: Look for a green run of this workflow at this sha
97
+ id: check
98
+ env:
99
+ GH_TOKEN: ${{ github.token }}
100
+ REPO: ${{ github.repository }}
101
+ RUN_ID: ${{ github.run_id }}
102
+ SHA: ${{ github.sha }}
103
+ run: |
104
+ tested=false
105
+ if ! command -v gh >/dev/null 2>&1; then
106
+ echo "::notice::gh is not installed on this runner — running the full suite (#418)."
107
+ elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
108
+ echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
109
+ elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
110
+ --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
111
+ echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
112
+ elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
113
+ tested=true
114
+ echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
115
+ echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
116
+ else
117
+ echo "No green run of this workflow at $SHA yet — running the full suite."
118
+ fi
119
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
120
+
72
121
  gitleaks:
73
122
  name: Secret scan (gitleaks)
123
+ needs: dedupe
124
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
74
125
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
75
126
  steps:
76
127
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -115,6 +166,8 @@ jobs:
115
166
 
116
167
  build:
117
168
  name: Build
169
+ needs: dedupe
170
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
118
171
  # A repo can adopt this template before it has any application code at all —
119
172
  # a fresh Tier B scaffold with decisions locked and a backlog filed, nothing
120
173
  # else. Unguarded, every step below still runs: "Install dependencies" warns
@@ -83,8 +83,59 @@ env:
83
83
  # jobs from different runs interleave, and trunk can wait behind branch runs.
84
84
  # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
85
85
  jobs:
86
+ # Already tested at this sha? (#418) — the claim push.
87
+ # A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
88
+ # claim record), so the branch's first push sits on a sha trunk has usually already
89
+ # run. Without this job that push re-runs the whole suite on a tested commit (~19% of
90
+ # all runs, measured across five adopting repos). This job runs ONLY on a ref's first
91
+ # push (`github.event.created`), checks nothing out, and asks one question: does THIS
92
+ # workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
93
+ # other job is skipped and the run concludes `success` — a branch-CI `green` that is
94
+ # true, because the same workflow passed at the same sha. Anything else — trunk still
95
+ # running, red, never run, `gh` missing, the API failing — and the suite runs as
96
+ # before (fail-open: this job never fails the run). Every later push has
97
+ # `created == false`, so a real commit always gets the full suite, with no extra hop.
98
+ # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
99
+ # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
100
+ # §4, "Branch CI"). This job is the one that ends green.
101
+ dedupe:
102
+ name: Already tested at this sha?
103
+ if: github.event_name == 'push' && github.event.created
104
+ runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
105
+ permissions:
106
+ actions: read
107
+ outputs:
108
+ tested: ${{ steps.check.outputs.tested }}
109
+ steps:
110
+ - name: Look for a green run of this workflow at this sha
111
+ id: check
112
+ env:
113
+ GH_TOKEN: ${{ github.token }}
114
+ REPO: ${{ github.repository }}
115
+ RUN_ID: ${{ github.run_id }}
116
+ SHA: ${{ github.sha }}
117
+ run: |
118
+ tested=false
119
+ if ! command -v gh >/dev/null 2>&1; then
120
+ echo "::notice::gh is not installed on this runner — running the full suite (#418)."
121
+ elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
122
+ echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
123
+ elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
124
+ --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
125
+ echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
126
+ elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
127
+ tested=true
128
+ echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
129
+ echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
130
+ else
131
+ echo "No green run of this workflow at $SHA yet — running the full suite."
132
+ fi
133
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
134
+
86
135
  gitleaks:
87
136
  name: Secret scan (gitleaks)
137
+ needs: dedupe
138
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
88
139
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
89
140
  steps:
90
141
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -129,6 +180,8 @@ jobs:
129
180
 
130
181
  build:
131
182
  name: Build (Python)
183
+ needs: dedupe
184
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
132
185
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
133
186
  defaults:
134
187
  run: