Skip to content

Commit 7e9524c

Browse files
committed
feat(release): automate single-package npm releases with HoverKraft
Prepare committed versions, consume an existing build, publish npm packages and GitHub release notes, and recover partial publication. Keep release validation and the consolidated decision record with the release workflow.
1 parent 0cc60c3 commit 7e9524c

47 files changed

Lines changed: 3565 additions & 60 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/dependabot.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ updates:
3535
versioning-strategy: increase
3636
directories:
3737
- "/"
38+
- "/actions/**/*"
3839
- "/tests/npm"
3940
- "/tests/pnpm"
4041
- "/tests/pnpm-package-manager"

‎.github/workflows/__shared-ci.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,17 @@ jobs:
1717
security-events: write
1818
statuses: write
1919

20+
test-release:
21+
name: Test release preparation and recovery
22+
uses: $/.github/workflows/__test-release.yml
23+
permissions:
24+
actions: read
25+
contents: read
26+
id-token: write
27+
packages: read
28+
pull-requests: write
29+
security-events: write
30+
2031
test-action-dependencies-cache:
2132
name: Test action "dependencies-cache"
2233
needs: linter
Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
name: Internal - Tests for package and release actions
2+
3+
on:
4+
workflow_call:
5+
6+
permissions: {}
7+
8+
jobs:
9+
continuous-integration:
10+
name: Unit tests for ${{ matrix.action }}
11+
strategy:
12+
fail-fast: false
13+
matrix:
14+
action:
15+
[package/restore, release/prepare, release/verify, release/finalize]
16+
uses: $/.github/workflows/continuous-integration.yml
17+
permissions:
18+
contents: read
19+
id-token: write
20+
packages: read
21+
pull-requests: write
22+
security-events: write
23+
with:
24+
working-directory: actions/${{ matrix.action }}
25+
build: null
26+
lint: null
27+
test: '{ "coverage": null }'
28+
29+
integration-tests:
30+
name: Test release action inputs, outputs and failures
31+
runs-on: ubuntu-latest
32+
permissions:
33+
actions: read
34+
contents: read
35+
steps:
36+
- name: Arrange - Checkout
37+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
38+
with:
39+
persist-credentials: false
40+
- uses: $/actions/setup-node
41+
with:
42+
working-directory: actions/release/prepare
43+
install-dependencies: "false"
44+
45+
- name: Act - Reject preparation of a private package
46+
id: private-project
47+
continue-on-error: true
48+
uses: $/actions/release/prepare
49+
with:
50+
working-directory: actions/release/prepare
51+
- name: Assert - Preparation failed
52+
env:
53+
OUTCOME: ${{ steps.private-project.outcome }}
54+
run: test "$OUTCOME" = failure
55+
56+
- name: Arrange - Create an installable release tarball
57+
id: fixture
58+
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
59+
with:
60+
script: |
61+
const fs = require('node:fs');
62+
const path = require('node:path');
63+
const { createHash } = require('node:crypto');
64+
const directory = fs.mkdtempSync(path.join(process.env.RUNNER_TEMP, 'release-fixture-'));
65+
const name = `hoverkraft-release-test-${context.runId}-${process.env.GITHUB_RUN_ATTEMPT}`;
66+
fs.writeFileSync(path.join(directory, 'package.json'), JSON.stringify({
67+
name, version: '1.2.3', bin: { 'release-fixture': 'cli.js' },
68+
scripts: { prepare: 'exit 91', prepack: 'exit 91', postpack: 'exit 91' },
69+
}));
70+
fs.writeFileSync(path.join(directory, 'cli.js'), '#!/usr/bin/env node\nconsole.log("1.2.3");\n', { mode: 0o755 });
71+
const { stdout } = await exec.getExecOutput('npm', ['pack', '--json', '--ignore-scripts'], { cwd: directory });
72+
const tarball = path.join(directory, JSON.parse(stdout)[0].filename);
73+
core.setOutput('name', name);
74+
core.setOutput('tarball', tarball);
75+
core.setOutput('digest', createHash('sha256').update(fs.readFileSync(tarball)).digest('hex'));
76+
core.setOutput('packages', [{ name, slug: name, version: '1.2.3', tag: 'v1.2.3', directory: '.' }]);
77+
78+
- name: Act - Reject an invalid CI artifact ID
79+
id: invalid-artifact
80+
continue-on-error: true
81+
uses: $/actions/release/verify
82+
with:
83+
packages: ${{ steps.fixture.outputs.packages }}
84+
build-artifact-id: "0"
85+
- name: Act - Reject a mismatched tarball version
86+
id: mismatched-version
87+
continue-on-error: true
88+
uses: $/actions/package/restore
89+
with:
90+
name: ${{ steps.fixture.outputs.name }}
91+
version: 9.9.9
92+
tarball-path: ${{ steps.fixture.outputs.tarball }}
93+
- name: Act - Check an unpublished npm version
94+
id: registry
95+
uses: $/actions/package/restore
96+
with:
97+
name: ${{ steps.fixture.outputs.name }}
98+
version: 1.2.3
99+
tarball-path: ${{ steps.fixture.outputs.tarball }}
100+
- name: Assert - Rejections and registry output
101+
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
102+
env:
103+
ARTIFACT_OUTCOME: ${{ steps.invalid-artifact.outcome }}
104+
VERSION_OUTCOME: ${{ steps.mismatched-version.outcome }}
105+
PUBLISHED: ${{ steps.registry.outputs.published }}
106+
TARBALL: ${{ steps.fixture.outputs.tarball }}
107+
EXPECTED_DIGEST: ${{ steps.fixture.outputs.digest }}
108+
with:
109+
script: |
110+
const assert = require('node:assert/strict');
111+
const fs = require('node:fs');
112+
const { createHash } = require('node:crypto');
113+
assert.equal(process.env.ARTIFACT_OUTCOME, 'failure');
114+
assert.equal(process.env.VERSION_OUTCOME, 'failure');
115+
assert.equal(process.env.PUBLISHED, 'false');
116+
assert.equal(createHash('sha256').update(fs.readFileSync(process.env.TARBALL)).digest('hex'), process.env.EXPECTED_DIGEST);
117+
118+
- name: Arrange - Upload the unpublished package
119+
id: unpublished-package
120+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
121+
with:
122+
name: unpublished-package-${{ github.run_id }}-${{ github.run_attempt }}
123+
path: ${{ steps.fixture.outputs.tarball }}
124+
archive: false
125+
if-no-files-found: error
126+
- name: Act - Publish dry run with package recovery enabled
127+
id: publish
128+
uses: $/actions/package/publish
129+
with:
130+
package-tarball-artifact-id: ${{ steps.unpublished-package.outputs.artifact-id }}
131+
skip-existing: "true"
132+
dry-run: "true"
133+
provenance: "false"
134+
- name: Assert - Publish preserved the unpublished tarball
135+
env:
136+
ORIGINAL_TARBALL: ${{ steps.fixture.outputs.tarball }}
137+
PUBLISH_TARBALL: ${{ steps.publish.outputs.package-tarball-path }}
138+
run: cmp "$ORIGINAL_TARBALL" "$PUBLISH_TARBALL"
139+
140+
- name: Act - Install and run the release package
141+
id: smoke
142+
uses: $/actions/package/test
143+
env:
144+
EXPECTED_PACKAGE_NAME: ${{ steps.fixture.outputs.name }}
145+
with:
146+
working-directory: actions/package/test
147+
tarball-path: ${{ steps.fixture.outputs.tarball }}
148+
name: ${{ steps.fixture.outputs.name }}
149+
version: 1.2.3
150+
commands: |
151+
test "$PWD" = "$GITHUB_WORKSPACE/actions/package/test"
152+
test "$PACKAGE_NAME" = "$EXPECTED_PACKAGE_NAME"
153+
test "$PACKAGE_VERSION" = 1.2.3
154+
consumer=$(mktemp -d)
155+
npm install --prefix "$consumer" --ignore-scripts --offline --no-audit --no-fund "$PACKAGE_TARBALL_PATH"
156+
test "$("$consumer/node_modules/.bin/release-fixture")" = "$PACKAGE_VERSION"
157+
touch "$RUNNER_TEMP/release-smoke-ran"
158+
- name: Act - Reject a failing package command
159+
id: failing-command
160+
continue-on-error: true
161+
uses: $/actions/package/test
162+
with:
163+
tarball-path: ${{ steps.fixture.outputs.tarball }}
164+
name: ${{ steps.fixture.outputs.name }}
165+
version: 1.2.3
166+
commands: exit 7
167+
- name: Act - Reject modified tarball bytes
168+
id: modified-tarball
169+
continue-on-error: true
170+
uses: $/actions/package/test
171+
with:
172+
tarball-path: ${{ steps.fixture.outputs.tarball }}
173+
name: ${{ steps.fixture.outputs.name }}
174+
version: 1.2.3
175+
commands: printf changed >> "$PACKAGE_TARBALL_PATH"
176+
- name: Assert - Smoke checks ran and rejected both failures
177+
env:
178+
SMOKE_OUTCOME: ${{ steps.smoke.outcome }}
179+
COMMAND_OUTCOME: ${{ steps.failing-command.outcome }}
180+
TARBALL_OUTCOME: ${{ steps.modified-tarball.outcome }}
181+
run: |
182+
test "$SMOKE_OUTCOME" = success
183+
test -f "$RUNNER_TEMP/release-smoke-ran"
184+
test "$COMMAND_OUTCOME" = failure
185+
test "$TARBALL_OUTCOME" = failure

‎.github/workflows/__test-workflow-continuous-integration.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,24 @@ jobs:
8282
tar -xOf "$TARBALL" package/dist/test.txt > "$RUNNER_TEMP/packaged-build.txt"
8383
cmp "$RUNNER_TEMP/prepared-fixture/dist/test.txt" "$RUNNER_TEMP/packaged-build.txt"
8484
test ! -d tests/npm/node_modules
85+
- name: Run package smoke checks with the project runtime
86+
uses: $/actions/package/test
87+
with:
88+
working-directory: tests/npm
89+
tarball-path: ${{ steps.package.outputs.package-tarball-path }}
90+
name: prepared-fixture
91+
version: 1.2.3
92+
commands: |
93+
node <<'NODE'
94+
const assert = require('node:assert/strict');
95+
const fs = require('node:fs');
96+
const expected = fs.readFileSync('.node-version', 'utf8').trim().split('.');
97+
assert.deepEqual(process.versions.node.split('.').slice(0, expected.length), expected);
98+
NODE
99+
test "$PACKAGE_NAME" = prepared-fixture
100+
test "$PACKAGE_VERSION" = 1.2.3
101+
tar -xOf "$PACKAGE_TARBALL_PATH" package/dist/test.txt > "$RUNNER_TEMP/smoke-output.txt"
102+
cmp "$RUNNER_TEMP/prepared-fixture/dist/test.txt" "$RUNNER_TEMP/smoke-output.txt"
85103
- name: Validate publishing the prepared tarball
86104
uses: $/actions/package/publish
87105
with:
Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
<!-- header:start -->
2+
3+
# GitHub Reusable Workflow: Prepare Node.js Package Release
4+
5+
<div align="center">
6+
<img src="https://opengraph.githubassets.com/5e6e6522b2be37aede8ce1464ef3152618d5ae56afc61474ac0df95cbf35ec3d/hoverkraft-tech/ci-github-nodejs" width="60px" align="center" alt="Prepare Node.js Package Release" />
7+
</div>
8+
9+
---
10+
11+
<!-- header:end -->
12+
<!-- badges:start -->
13+
14+
[![Release](https://img.shields.io/github/v/release/hoverkraft-tech/ci-github-nodejs)](https://github.com/hoverkraft-tech/ci-github-nodejs/releases)
15+
[![License](https://img.shields.io/github/license/hoverkraft-tech/ci-github-nodejs)](http://choosealicense.com/licenses/mit/)
16+
[![Stars](https://img.shields.io/github/stars/hoverkraft-tech/ci-github-nodejs?style=social)](https://img.shields.io/github/stars/hoverkraft-tech/ci-github-nodejs?style=social)
17+
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/hoverkraft-tech/ci-github-nodejs/blob/main/CONTRIBUTING.md)
18+
19+
<!-- badges:end -->
20+
<!-- overview:start -->
21+
22+
## Overview
23+
24+
Prepare Node.js package versions and lockfiles before building the release.
25+
Dispatches the calling workflow at the prepared tag; that run can build and publish.
26+
See [the release guide](release.md).
27+
28+
### Permissions
29+
30+
- **`actions`**: `write`
31+
- **`contents`**: `write`
32+
- **`pull-requests`**: `read`
33+
34+
<!-- overview:end -->
35+
<!-- inputs:start -->
36+
37+
## Inputs
38+
39+
### Workflow Call Inputs
40+
41+
| **Input** | **Description** | **Required** | **Type** | **Default** |
42+
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------ | ---------- | ----------- |
43+
| **`working-directory`** | Public npm project directory containing its package.json and lockfile. | **false** | **string** | `.` |
44+
| **`github-app-client-id`** | Optional GitHub App client ID, paired with the github-app-key secret to generate a repository-scoped preparation token. | **false** | **string** | - |
45+
46+
<!-- inputs:end -->
47+
<!-- secrets:start -->
48+
49+
## Secrets
50+
51+
| **Secret** | **Description** | **Required** |
52+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
53+
| **`github-app-key`** | Optional GitHub App private key, paired with the github-app-client-id input. The identity must be permitted by branch and tag rules. | **false** |
54+
55+
<!-- secrets:end -->
56+
<!-- outputs:start -->
57+
58+
## Outputs
59+
60+
| **Output** | **Description** |
61+
| -------------- | -------------------------------------------------------------------------------------------------------- |
62+
| **`status`** | no-changes, dispatched, released or ready. Only ready should start building and publication in this run. |
63+
| **`packages`** | JSON package list for the release workflow's packages input. Available when status is ready. |
64+
65+
<!-- outputs:end -->
66+
<!-- contributing:start -->
67+
68+
## Contributing
69+
70+
Contributions are welcome! Please see the [contributing guidelines](https://github.com/hoverkraft-tech/ci-github-nodejs/blob/main/CONTRIBUTING.md) for more details.
71+
72+
<!-- contributing:end -->
73+
<!-- security:start -->
74+
<!-- security:end -->
75+
<!-- license:start -->
76+
77+
## License
78+
79+
This project is licensed under the MIT License.
80+
81+
SPDX-License-Identifier: MIT
82+
83+
Copyright © 2026 hoverkraft-tech
84+
85+
For more details, see the [license](http://choosealicense.com/licenses/mit/).
86+
87+
<!-- license:end -->
88+
<!-- generated:start -->
89+
90+
---
91+
92+
This documentation was automatically generated by [CI Dokumentor](https://github.com/hoverkraft-tech/ci-dokumentor).
93+
94+
<!-- generated:end -->
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Prepare Node.js package versions and lockfiles before building the release.
2+
# Dispatches the calling workflow at the prepared tag; that run can build and publish.
3+
# See [the release guide](release.md).
4+
name: Prepare Node.js Package Release
5+
6+
on:
7+
workflow_call:
8+
inputs:
9+
working-directory:
10+
description: Public npm project directory containing its package.json and lockfile.
11+
type: string
12+
default: .
13+
github-app-client-id:
14+
description: Optional GitHub App client ID, paired with the github-app-key secret to generate a repository-scoped preparation token.
15+
type: string
16+
required: false
17+
secrets:
18+
github-app-key:
19+
description: Optional GitHub App private key, paired with the github-app-client-id input. The identity must be permitted by branch and tag rules.
20+
required: false
21+
outputs:
22+
status:
23+
description: no-changes, dispatched, released or ready. Only ready should start building and publication in this run.
24+
value: ${{ jobs.prepare.outputs.status }}
25+
packages:
26+
description: JSON package list for the release workflow's packages input. Available when status is ready.
27+
value: ${{ jobs.prepare.outputs.packages }}
28+
29+
permissions: {}
30+
31+
concurrency:
32+
group: node-release-prepare-${{ github.repository }}-${{ inputs.working-directory }}
33+
cancel-in-progress: false
34+
35+
jobs:
36+
prepare:
37+
name: Prepare package release
38+
runs-on: ubuntu-latest
39+
timeout-minutes: 20
40+
env:
41+
HAS_APP_PRIVATE_KEY: ${{ secrets.github-app-key != '' }}
42+
permissions:
43+
actions: write
44+
contents: write
45+
pull-requests: read
46+
outputs:
47+
status: ${{ steps.prepare.outputs.status }}
48+
packages: ${{ steps.prepare.outputs.packages }}
49+
steps:
50+
- name: Generate release App token
51+
id: release-token
52+
if: inputs.github-app-client-id != '' || env.HAS_APP_PRIVATE_KEY == 'true'
53+
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
54+
with:
55+
client-id: ${{ inputs.github-app-client-id }}
56+
private-key: ${{ secrets.github-app-key }} # zizmor: ignore[secrets-outside-env] reusable workflow credentials are explicitly supplied by the caller
57+
permission-actions: write
58+
permission-contents: write
59+
permission-pull-requests: read
60+
- id: prepare
61+
uses: $/actions/release/prepare
62+
with:
63+
working-directory: ${{ inputs.working-directory }}
64+
github-token: ${{ steps.release-token.outputs.token || github.token }}

0 commit comments

Comments
 (0)