@futurelastic/colab-handbook 1.22.1-rc.2 → 1.22.1-rc.3

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.22.1-rc.2"
36
+ "version": "1.22.1-rc.3"
37
37
  }
@@ -37,15 +37,30 @@
37
37
  # artifact per platform named `<artifact-prefix><os>-<arch>`, then:
38
38
  #
39
39
  # dist:
40
- # needs: [build] # your matrix build, one upload-artifact per platform
40
+ # needs: [build] # your matrix build, one artifact-store/upload per platform
41
41
  # uses: ./.github/workflows/dist-refs.yml
42
42
  # permissions:
43
43
  # contents: write
44
+ # secrets: inherit # the artifact-store secrets below — a called workflow
45
+ # # reads no secret it is not passed
44
46
  # with:
45
47
  # version: ${{ needs.release.outputs.tag }} # vX.Y.Z or vX.Y.Z-rc.N
46
48
  # platforms: darwin-arm64 darwin-x64 linux-x64 linux-arm64 win32-x64
47
49
  # bin: mytool # EDIT: the launcher's binary name
48
50
  #
51
+ # THE ARTIFACTS GO THROUGH YOUR ARTIFACT STORE, not GitHub's capped artifact allowance
52
+ # (CONVENTIONS.md §7, "CI artifacts", #601). The build uploads each platform with
53
+ # artifact-store/upload, and the download step below reads them back with
54
+ # artifact-store/download, both with the same five secrets: ARTIFACT_STORE_ENDPOINT,
55
+ # ARTIFACT_STORE_BUCKET, ARTIFACT_STORE_ACCESS_KEY, ARTIFACT_STORE_SECRET_KEY and
56
+ # ARTIFACT_STORE_REGION (docs/artifact-store.md in the handbook). Pass them with
57
+ # `secrets: inherit` as above, or one by one under `secrets:`. With no bucket secret the
58
+ # download runs with `backend: github`, i.e. GitHub's own artifact action, so a copy works
59
+ # before its store exists — the build's uploads must then use the same fallback.
60
+ # ⚠ REGION: requests are signed for the region and default to us-east-1. A store configured
61
+ # with any other region answers 400 to every GET signed for the wrong one, so set
62
+ # ARTIFACT_STORE_REGION and pass it on every call site, uploads included.
63
+ #
49
64
  # Each artifact must hold the binary at its top level, named `<bin>` (`<bin>.exe` on win32-*).
50
65
  # Anything else in the artifact rides along in the same ref and is covered by SHA256SUMS.
51
66
  #
@@ -92,6 +107,24 @@ on:
92
107
  required: false
93
108
  type: string
94
109
  default: 'dist-'
110
+ # The artifact store's connection (#601). All optional: with no bucket the download falls
111
+ # back to GitHub's artifact action. `secrets: inherit` from the caller passes them too.
112
+ secrets:
113
+ ARTIFACT_STORE_ENDPOINT:
114
+ description: 'S3 endpoint URL. Empty means the AWS default endpoint.'
115
+ required: false
116
+ ARTIFACT_STORE_BUCKET:
117
+ description: 'Bucket the build uploaded to. Empty = backend github.'
118
+ required: false
119
+ ARTIFACT_STORE_ACCESS_KEY:
120
+ description: 'Access key id for the store.'
121
+ required: false
122
+ ARTIFACT_STORE_SECRET_KEY:
123
+ description: 'Secret access key for the store.'
124
+ required: false
125
+ ARTIFACT_STORE_REGION:
126
+ description: 'Region the store signs for. Empty means us-east-1.'
127
+ required: false
95
128
 
96
129
  permissions:
97
130
  contents: write
@@ -120,10 +153,26 @@ jobs:
120
153
  with:
121
154
  fetch-depth: 1
122
155
 
123
- - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
156
+ # Through the artifact store (#601): the secrets and the region trap are in the header.
157
+ # EDIT: `@HANDBOOK_TAG` is the handbook release this copy calls — `colab template` writes
158
+ # the version it stamps; by hand, pin a tag or a commit, never a branch. Copied the action
159
+ # into this repo instead? `uses: ./.github/actions/artifact-store/download`.
160
+ - name: Download the per-platform artifacts
161
+ uses: futurelastic/colab-handbook/.github/actions/artifact-store/download@HANDBOOK_TAG
124
162
  with:
163
+ # Empty name + pattern = every `<artifact-prefix>*` artifact of this run, each in
164
+ # dist-in/<name>/ — the layout the push step reads.
125
165
  pattern: ${{ inputs.artifact-prefix }}*
126
166
  path: dist-in
167
+ # No bucket secret → GitHub's own artifact action, unchanged. The bucket, not the
168
+ # endpoint, decides: an empty endpoint is a real store (the AWS default), a missing
169
+ # bucket is none.
170
+ backend: ${{ secrets.ARTIFACT_STORE_BUCKET != '' && 's3' || 'github' }}
171
+ endpoint: ${{ secrets.ARTIFACT_STORE_ENDPOINT }}
172
+ bucket: ${{ secrets.ARTIFACT_STORE_BUCKET }}
173
+ access-key: ${{ secrets.ARTIFACT_STORE_ACCESS_KEY }}
174
+ secret-key: ${{ secrets.ARTIFACT_STORE_SECRET_KEY }}
175
+ region: ${{ secrets.ARTIFACT_STORE_REGION }}
127
176
 
128
177
  - name: Push one orphan ref per platform
129
178
  env:
@@ -85,6 +85,18 @@ env:
85
85
  # is no artifact lying around from the CI run on main. To use this you must add a
86
86
  # build job to THIS file that uploads an artifact, and make the release job
87
87
  # `needs:` it. Left false because most of our repos build on the deploy target.
88
+ #
89
+ # The files come through the organisation's artifact store, not GitHub's capped
90
+ # artifact allowance (CONVENTIONS.md §7, "CI artifacts", #601): the "Download build
91
+ # artifacts" step calls artifact-store/download, so your build job uploads with
92
+ # artifact-store/upload and the same five secrets — ARTIFACT_STORE_ENDPOINT,
93
+ # ARTIFACT_STORE_BUCKET, ARTIFACT_STORE_ACCESS_KEY, ARTIFACT_STORE_SECRET_KEY and
94
+ # ARTIFACT_STORE_REGION (docs/artifact-store.md in the handbook). Until the bucket
95
+ # secret exists the step runs with `backend: github`, i.e. GitHub's own artifact
96
+ # action, so a fresh copy works before its store does.
97
+ # ⚠ REGION: requests are signed for the region and default to us-east-1. A store
98
+ # configured with any other region answers 400 to every GET signed for the wrong one,
99
+ # so set ARTIFACT_STORE_REGION — on the upload call site too, not just this one.
88
100
  ATTACH_ARTIFACTS: "false"
89
101
  # Empty means every artifact from this run.
90
102
  ARTIFACT_NAME: ""
@@ -228,13 +240,26 @@ jobs:
228
240
  # Same summary into the run page, so it is readable without opening Releases.
229
241
  cat /tmp/body.md >> "$GITHUB_STEP_SUMMARY"
230
242
 
243
+ # Through the artifact store (#601): see ATTACH_ARTIFACTS above for the secrets and
244
+ # the region trap. EDIT: `@HANDBOOK_TAG` is the handbook release this copy calls —
245
+ # `colab template` writes the version it stamps; by hand, pin a tag or a commit, never
246
+ # a branch. Copied the action into this repo instead? `uses: ./.github/actions/artifact-store/download`.
231
247
  - name: Download build artifacts
232
248
  if: env.ATTACH_ARTIFACTS == 'true'
233
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
249
+ uses: futurelastic/colab-handbook/.github/actions/artifact-store/download@HANDBOOK_TAG
234
250
  with:
235
- # Empty name = every artifact produced by this run.
251
+ # Empty name = every artifact produced by this run, each in release-artifacts/<name>/.
236
252
  name: ${{ env.ARTIFACT_NAME }}
237
253
  path: release-artifacts
254
+ # No bucket secret yet → GitHub's own artifact action, unchanged. The bucket, not the
255
+ # endpoint, decides: an empty endpoint is a real store (the AWS default), a missing
256
+ # bucket is none.
257
+ backend: ${{ secrets.ARTIFACT_STORE_BUCKET != '' && 's3' || 'github' }}
258
+ endpoint: ${{ secrets.ARTIFACT_STORE_ENDPOINT }}
259
+ bucket: ${{ secrets.ARTIFACT_STORE_BUCKET }}
260
+ access-key: ${{ secrets.ARTIFACT_STORE_ACCESS_KEY }}
261
+ secret-key: ${{ secrets.ARTIFACT_STORE_SECRET_KEY }}
262
+ region: ${{ secrets.ARTIFACT_STORE_REGION }}
238
263
  continue-on-error: true
239
264
 
240
265
  - name: List artifacts to attach
@@ -76,8 +76,10 @@ function substituteTrunk(text, p) {
76
76
  * a refreshed file stays byte-identical to what `colab template <name> --force` would write.
77
77
  */
78
78
  function renderForRepo(name, body, doc, version) {
79
- if (!/^ci-/.test(String(name || ''))) return body;
79
+ // The pin applies to every template, as `colab template` writes it (#754: release-tag and dist-refs
80
+ // call the artifact-store action at `@HANDBOOK_TAG`); only the trunk refs are CI-template-only.
80
81
  const pinned = version ? pinHandbookTag(body, version).text : body;
82
+ if (!/^ci-/.test(String(name || ''))) return pinned;
81
83
  const p = protectedRefs(doc);
82
84
  return p ? substituteTrunk(pinned, p).text : pinned;
83
85
  }