Skip to content

Commit 8ffa243

Browse files
committed
refactor(release): pass workspace tarballs explicitly to finalization
2 parents 005d164 + 8082c28 commit 8ffa243

7 files changed

Lines changed: 189 additions & 62 deletions

File tree

‎.github/workflows/release.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -457,6 +457,13 @@ It checks the exact version on every attempt, restores the original registry tar
457457
when present, skips npm publication, and returns its local path for assets so the
458458
remaining release steps can resume. Registry and integrity errors still fail the job.
459459
460+
Pass that `package-tarball-path` directly to `release/finalize`, with the desired
461+
`.tgz` filename as `asset-name`. Finalization checks the existing asset's digest
462+
and stages the file only if it is missing. Callers do not need to copy the tarball
463+
into a predefined directory. For workspace releases, pass the downloaded tarball
464+
glob as `package-tarball-path` and leave `asset-name` empty to preserve the names
465+
set before transfer between jobs.
466+
460467
npm publication across several packages cannot be atomic. Check exact package
461468
versions before retrying; published versions cannot be overwritten. Restore original
462469
published bytes for release assets, verify integrity and existing asset digests, and

‎.github/workflows/release.yml‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -112,17 +112,23 @@ jobs:
112112
version: ${{ matrix.package.version }}
113113
recover-existing: "true"
114114
tag: latest
115-
- name: Prepare release asset
115+
- name: Name tarball for transfer between jobs
116+
id: asset
117+
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
116118
env:
117119
PACKAGE_TARBALL: ${{ steps.publish.outputs.package-tarball-path }}
118120
ASSET_NAME: ${{ matrix.package.slug }}-${{ matrix.package.version }}.tgz
119-
run: |
120-
mkdir -p "$RUNNER_TEMP/release-assets"
121-
cp "$PACKAGE_TARBALL" "$RUNNER_TEMP/release-assets/$ASSET_NAME"
121+
with:
122+
script: |
123+
const path = require('node:path');
124+
const source = process.env.PACKAGE_TARBALL;
125+
const destination = path.join(path.dirname(source), process.env.ASSET_NAME);
126+
if (source !== destination) await io.mv(source, destination);
127+
core.setOutput('path', destination);
122128
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
123129
with:
124130
name: release-assets-${{ matrix.package.slug }}
125-
path: ${{ runner.temp }}/release-assets/*.tgz
131+
path: ${{ steps.asset.outputs.path }}
126132
overwrite: true
127133
if-no-files-found: error
128134

@@ -140,11 +146,13 @@ jobs:
140146
matrix:
141147
release: ${{ fromJSON(needs.verify.outputs.releases) }}
142148
steps:
143-
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
149+
- id: release-assets
150+
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
144151
with:
145152
pattern: ${{ matrix.release.artifactPattern }}
146153
merge-multiple: true
147154
path: ${{ runner.temp }}/release-assets
148155
- uses: $/actions/release/finalize
149156
with:
150157
tag: ${{ matrix.release.tag }}
158+
package-tarball-path: ${{ steps.release-assets.outputs.download-path }}/*.tgz

‎actions/release/finalize/README.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,18 @@
2222

2323
## Overview
2424

25-
Verify published npm tarballs staged in RUNNER_TEMP/release-assets against existing assets, then upload missing assets and publish the draft with HoverKraft release/update using GITHUB_TOKEN.
25+
Verify published npm tarballs against release assets, then stage only missing files and publish the draft with HoverKraft release/update using GITHUB_TOKEN.
2626

2727
<!-- overview:end -->
2828
<!-- inputs:start -->
2929

3030
## Inputs
3131

32-
| **Input** | **Description** | **Required** | **Default** |
33-
| --------- | ---------------------- | ------------ | ----------- |
34-
| **`tag`** | Committed release tag. | **true** | - |
32+
| **Input** | **Description** | **Required** | **Default** |
33+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | ----------- |
34+
| **`tag`** | Committed release tag. | **true** | - |
35+
| **`package-tarball-path`** | Local tarball path returned by package/publish, or a glob matching downloaded workspace tarballs. Use the original npm bytes restored during recovery. | **true** | - |
36+
| **`asset-name`** | Plain .tgz filename for a single tarball. Leave empty to preserve matched tarball filenames. | **false** | - |
3537

3638
<!-- inputs:end -->
3739
<!-- secrets:start -->

‎actions/release/finalize/action.yml‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
name: Finalize Node.js release
2-
description: Verify published npm tarballs staged in RUNNER_TEMP/release-assets against existing assets, then upload missing assets and publish the draft with HoverKraft release/update using GITHUB_TOKEN.
2+
description: Verify published npm tarballs against release assets, then stage only missing files and publish the draft with HoverKraft release/update using GITHUB_TOKEN.
33
author: hoverkraft
44
branding:
55
icon: tag
@@ -8,6 +8,12 @@ inputs:
88
tag:
99
description: Committed release tag.
1010
required: true
11+
package-tarball-path:
12+
description: Local tarball path returned by package/publish, or a glob matching downloaded workspace tarballs. Use the original npm bytes restored during recovery.
13+
required: true
14+
asset-name:
15+
description: Plain .tgz filename for a single tarball. Leave empty to preserve matched tarball filenames.
16+
default: ""
1117
runs:
1218
using: composite
1319
steps:
@@ -16,11 +22,17 @@ runs:
1622
env:
1723
ACTION_PATH: ${{ github.action_path }}
1824
RELEASE_TAG: ${{ inputs.tag }}
19-
ASSET_DIRECTORY: ${{ runner.temp }}/release-assets
25+
PACKAGE_TARBALL_PATH: ${{ inputs.package-tarball-path }}
26+
ASSET_NAME: ${{ inputs.asset-name }}
27+
RUNNER_TEMP: ${{ runner.temp }}
2028
with:
2129
script: |
2230
const releaseAssets = require(`${process.env.ACTION_PATH}/index.js`);
23-
const { release, pendingDirectory, hasAssets } = await releaseAssets.prepareAssets({ github, glob, repo: context.repo, tag: process.env.RELEASE_TAG, directory: process.env.ASSET_DIRECTORY });
31+
const { release, pendingDirectory, hasAssets } = await releaseAssets.prepareAssets({
32+
github, glob, repo: context.repo, tag: process.env.RELEASE_TAG,
33+
tarballPath: process.env.PACKAGE_TARBALL_PATH, assetName: process.env.ASSET_NAME,
34+
tempDirectory: process.env.RUNNER_TEMP,
35+
});
2436
core.setOutput('release-id', release.id);
2537
core.setOutput('published', String(!release.draft));
2638
core.setOutput('pending-directory', pendingDirectory);

‎actions/release/finalize/index.js‎

Lines changed: 44 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -19,27 +19,52 @@ async function findRelease(github, repo, tag) {
1919
}
2020
}
2121

22-
async function prepareAssets({ github, glob, repo, tag, directory }) {
22+
async function prepareAssets({
23+
github,
24+
glob,
25+
repo,
26+
tag,
27+
tarballPath,
28+
assetName,
29+
tempDirectory,
30+
}) {
31+
let files;
32+
if (assetName) {
33+
files = [{ file: tarballPath, name: assetName }];
34+
} else {
35+
const globber = await glob.create(tarballPath, {
36+
followSymbolicLinks: false,
37+
matchDirectories: false,
38+
implicitDescendants: false,
39+
});
40+
files = (await globber.glob())
41+
.filter((file) => fs.lstatSync(file).isFile())
42+
.map((file) => ({ file, name: path.basename(file) }));
43+
}
44+
if (!files.length)
45+
throw new Error("No package tarballs available to attach.");
46+
const names = new Set();
47+
for (const { file, name } of files) {
48+
if (
49+
typeof name !== "string" ||
50+
!/^[A-Za-z0-9][A-Za-z0-9._-]*\.tgz$/.test(name)
51+
)
52+
throw new Error("asset-name must be a plain .tgz filename.");
53+
if (!fs.lstatSync(file).isFile())
54+
throw new Error("package-tarball-path must point to a regular file.");
55+
if (names.has(name))
56+
throw new Error(`Duplicate release asset name ${name}.`);
57+
names.add(name);
58+
}
2359
const release = await findRelease(github, repo, tag);
2460
if (!release) throw new Error(`No release found for ${tag}.`);
2561
const assets = await github.paginate(github.rest.repos.listReleaseAssets, {
2662
...repo,
2763
release_id: release.id,
2864
per_page: 100,
2965
});
30-
const globber = await glob.create(path.join(directory, "*.tgz"), {
31-
followSymbolicLinks: false,
32-
matchDirectories: false,
33-
implicitDescendants: false,
34-
});
35-
const files = (await globber.glob()).filter((file) =>
36-
fs.lstatSync(file).isFile(),
37-
);
38-
if (!files.length)
39-
throw new Error("No package tarballs available to attach.");
4066
const missing = [];
41-
for (const file of files) {
42-
const name = path.basename(file);
67+
for (const { file, name } of files) {
4368
const data = fs.readFileSync(file);
4469
const digest = `sha256:${createHash("sha256").update(data).digest("hex")}`;
4570
const existing = assets.find((asset) => asset.name === name);
@@ -54,10 +79,14 @@ async function prepareAssets({ github, glob, repo, tag, directory }) {
5479
throw new Error(`Published release is missing expected asset ${name}.`);
5580
missing.push({ name, data });
5681
}
57-
const pendingDirectory = fs.mkdtempSync(path.join(directory, "pending-"));
82+
if (!missing.length)
83+
return { release, pendingDirectory: "", hasAssets: false };
84+
const pendingDirectory = fs.mkdtempSync(
85+
path.join(tempDirectory, "release-pending-"),
86+
);
5887
for (const { name, data } of missing)
5988
fs.writeFileSync(path.join(pendingDirectory, name), data);
60-
return { release, pendingDirectory, hasAssets: missing.length > 0 };
89+
return { release, pendingDirectory, hasAssets: true };
6190
}
6291

6392
module.exports = { prepareAssets };

‎actions/release/finalize/index.test.js‎

Lines changed: 99 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ function directory(t) {
1515
function assetsFixture(t) {
1616
const root = directory(t);
1717
const data = Buffer.from("published package");
18-
fs.writeFileSync(path.join(root, "example-core-1.2.0.tgz"), data);
18+
const tarballPath = path.join(root, "downloaded-artifact.tgz");
19+
fs.writeFileSync(tarballPath, data);
1920
const release = { id: 1, draft: true };
2021
const assets = [];
2122
const github = {
@@ -35,12 +36,14 @@ function assetsFixture(t) {
3536
glob,
3637
repo: { owner: "example", repo: "project" },
3738
tag: "v1.2.0",
38-
directory: root,
39+
tarballPath,
40+
assetName: "example-core-1.2.0.tgz",
41+
tempDirectory: root,
3942
},
4043
};
4144
}
4245

43-
test("stages only missing package bytes for HoverKraft upload and skips identical assets", async (t) => {
46+
test("stages the explicit tarball under its release name and skips identical assets", async (t) => {
4447
const f = assetsFixture(t);
4548
const result = await releaseAssets.prepareAssets(f.args);
4649
assert.equal(result.hasAssets, true);
@@ -50,13 +53,15 @@ test("stages only missing package bytes for HoverKraft upload and skips identica
5053
),
5154
f.data,
5255
);
56+
assert.deepEqual(fs.readdirSync(result.pendingDirectory), [f.args.assetName]);
57+
assert.deepEqual(fs.readFileSync(f.args.tarballPath), f.data);
5358
f.assets.push({
5459
name: "example-core-1.2.0.tgz",
5560
digest: `sha256:${createHash("sha256").update(f.data).digest("hex")}`,
5661
});
5762
const retry = await releaseAssets.prepareAssets(f.args);
5863
assert.equal(retry.hasAssets, false);
59-
assert.deepEqual(fs.readdirSync(retry.pendingDirectory), []);
64+
assert.equal(retry.pendingDirectory, "");
6065
f.release.draft = false;
6166
assert.equal((await releaseAssets.prepareAssets(f.args)).hasAssets, false);
6267
});
@@ -76,42 +81,49 @@ test("does not overwrite mismatched assets or modify an incomplete published rel
7681
);
7782
});
7883

79-
test("partial asset recovery passes only missing tarballs to the uploader", async (t) => {
84+
test("attaches only the requested file even when other tarballs are present", async (t) => {
8085
const f = assetsFixture(t);
81-
const name = "example-cli-1.2.0.tgz";
82-
fs.writeFileSync(path.join(f.args.directory, name), "second package");
83-
f.assets.push({
84-
name: "example-core-1.2.0.tgz",
85-
digest: `sha256:${createHash("sha256").update(f.data).digest("hex")}`,
86-
});
87-
const result = await releaseAssets.prepareAssets(f.args);
88-
assert.equal(result.hasAssets, true);
89-
assert.deepEqual(fs.readdirSync(result.pendingDirectory), [name]);
90-
assert.equal(
91-
fs.readFileSync(path.join(result.pendingDirectory, name), "utf8"),
92-
"second package",
86+
fs.writeFileSync(
87+
path.join(f.args.tempDirectory, "unrelated.tgz"),
88+
"other package",
9389
);
90+
const result = await releaseAssets.prepareAssets(f.args);
91+
assert.deepEqual(fs.readdirSync(result.pendingDirectory), [f.args.assetName]);
9492
});
9593

96-
test("asset discovery excludes nested tarballs, directories and symbolic links", async (t) => {
94+
test("rejects asset names that could escape staging or are not tarball filenames", async (t) => {
9795
const f = assetsFixture(t);
98-
const nested = path.join(f.args.directory, "previous-attempt");
99-
fs.mkdirSync(nested);
100-
fs.writeFileSync(path.join(nested, "ignored.tgz"), "previous attempt");
101-
fs.mkdirSync(path.join(f.args.directory, "directory.tgz"));
102-
fs.symlinkSync(
103-
path.join(nested, "ignored.tgz"),
104-
path.join(f.args.directory, "link.tgz"),
105-
);
106-
const result = await releaseAssets.prepareAssets(f.args);
107-
assert.deepEqual(fs.readdirSync(result.pendingDirectory), [
108-
"example-core-1.2.0.tgz",
96+
for (const assetName of [
97+
"../outside.tgz",
98+
"/outside.tgz",
99+
"dir\\outside.tgz",
100+
"package.zip",
101+
"bad\nname.tgz",
102+
]) {
103+
await assert.rejects(
104+
releaseAssets.prepareAssets({ ...f.args, assetName }),
105+
/asset-name must be a plain .tgz filename/,
106+
);
107+
}
108+
assert.deepEqual(fs.readdirSync(f.args.tempDirectory), [
109+
"downloaded-artifact.tgz",
109110
]);
110-
fs.unlinkSync(path.join(f.args.directory, "example-core-1.2.0.tgz"));
111-
await assert.rejects(
112-
releaseAssets.prepareAssets(f.args),
113-
/No package tarballs/,
114-
);
111+
});
112+
113+
test("rejects missing tarballs, directories and symbolic links", async (t) => {
114+
const f = assetsFixture(t);
115+
const folder = path.join(f.args.tempDirectory, "directory.tgz");
116+
const link = path.join(f.args.tempDirectory, "link.tgz");
117+
fs.mkdirSync(folder);
118+
fs.symlinkSync(f.args.tarballPath, link);
119+
for (const tarballPath of [folder, link]) {
120+
await assert.rejects(
121+
releaseAssets.prepareAssets({ ...f.args, tarballPath }),
122+
/package-tarball-path must point to a regular file/,
123+
);
124+
}
125+
fs.unlinkSync(f.args.tarballPath);
126+
await assert.rejects(releaseAssets.prepareAssets(f.args), /ENOENT/);
115127
});
116128

117129
test("recovers draft assets through release listing and propagates lookup failures", async (t) => {
@@ -134,3 +146,56 @@ test("recovers draft assets through release listing and propagates lookup failur
134146
};
135147
await assert.rejects(releaseAssets.prepareAssets(f.args), /Forbidden/);
136148
});
149+
150+
test("workspace recovery stages only missing tarballs from the explicit glob", async (t) => {
151+
const f = assetsFixture(t);
152+
const root = f.args.tempDirectory;
153+
fs.renameSync(f.args.tarballPath, path.join(root, f.args.assetName));
154+
f.assets.push({
155+
name: f.args.assetName,
156+
digest: `sha256:${createHash("sha256").update(f.data).digest("hex")}`,
157+
});
158+
const missingName = "example-cli-1.2.0.tgz";
159+
fs.writeFileSync(path.join(root, missingName), "second package");
160+
const nested = path.join(root, "previous-attempt");
161+
fs.mkdirSync(nested);
162+
fs.writeFileSync(path.join(nested, "ignored.tgz"), "previous attempt");
163+
fs.mkdirSync(path.join(root, "directory.tgz"));
164+
fs.symlinkSync(path.join(nested, "ignored.tgz"), path.join(root, "link.tgz"));
165+
const args = {
166+
...f.args,
167+
tarballPath: path.join(root, "*.tgz"),
168+
assetName: "",
169+
};
170+
const result = await releaseAssets.prepareAssets(args);
171+
assert.deepEqual(fs.readdirSync(result.pendingDirectory), [missingName]);
172+
assert.equal(
173+
fs.readFileSync(path.join(result.pendingDirectory, missingName), "utf8"),
174+
"second package",
175+
);
176+
await assert.rejects(
177+
releaseAssets.prepareAssets({
178+
...args,
179+
tarballPath: path.join(root, "absent-*.tgz"),
180+
}),
181+
/No package tarballs/,
182+
);
183+
});
184+
185+
test("rejects workspace tarballs with duplicate asset filenames", async (t) => {
186+
const f = assetsFixture(t);
187+
const nested = path.join(f.args.tempDirectory, "nested");
188+
fs.mkdirSync(nested);
189+
fs.writeFileSync(
190+
path.join(nested, path.basename(f.args.tarballPath)),
191+
"other package",
192+
);
193+
await assert.rejects(
194+
releaseAssets.prepareAssets({
195+
...f.args,
196+
tarballPath: path.join(f.args.tempDirectory, "**/*.tgz"),
197+
assetName: "",
198+
}),
199+
/Duplicate release asset name/,
200+
);
201+
});

‎docs/adr/0001-release-orchestration.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -384,3 +384,7 @@ compositions. Repository migrations and settings changes remain each owner's wor
384384
`recover-existing` to describe restoring original registry bytes when resuming a
385385
release. Keep the default false for standalone publication and enable recovery
386386
in release workflows. Registry and integrity failures remain errors.
387+
- **2026-11-04, explicit release asset handoff:** Pass the published or recovered
388+
tarball path and its asset name directly to finalization. This supersedes the
389+
implicit `RUNNER_TEMP/release-assets` contract and the workflow's extra copy.
390+
Finalization stages missing bytes once, preserving digest checks on retries.

0 commit comments

Comments
 (0)