Skip to content

Commit e773dc8

Browse files
Copilotneilime
Copilot
and
neilime
committed
feat(workflows): add release.yml reusable workflow and documentation
Co-authored-by: neilime <[email protected]>
1 parent 07ae5bd commit e773dc8

File tree

3 files changed

+905
-0
lines changed

3 files changed

+905
-0
lines changed

‎.github/workflows/release.md‎

Lines changed: 384 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,384 @@
1+
<!-- header:start -->
2+
3+
# GitHub Reusable Workflow: Node.js Release
4+
5+
<div align="center">
6+
<img src="https://opengraph.githubassets.com/0e54b99e7f052e2a353659bcb048b76224cb355f919e9772252049df8eec3976/hoverkraft-tech/ci-github-nodejs" width="60px" align="center" alt="Node.js Release" />
7+
</div>
8+
9+
---
10+
11+
<!-- header:end -->
12+
13+
<!-- badges:start -->
14+
15+
[![Release](https://img.shields.io/github/v/release/hoverkraft-tech/ci-github-nodejs)](https://github.com/hoverkraft-tech/ci-github-nodejs/releases)
16+
[![License](https://img.shields.io/github/license/hoverkraft-tech/ci-github-nodejs)](http://choosealicense.com/licenses/mit/)
17+
[![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)
18+
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/hoverkraft-tech/ci-github-nodejs/blob/main/CONTRIBUTING.md)
19+
20+
<!-- badges:end -->
21+
22+
<!-- overview:start -->
23+
24+
## Overview
25+
26+
Workflow to release Node.js packages with support for:
27+
28+
- Building the package before publishing
29+
- Generating documentation (optional)
30+
- Publishing to various registries (npm, GitHub Packages)
31+
- Provenance attestation for npm packages
32+
- Distribution tags for versioning
33+
34+
### Permissions
35+
36+
- **`contents`**: `read`
37+
- **`id-token`**: `write` (required for provenance)
38+
- **`packages`**: `write`
39+
40+
<!-- overview:end -->
41+
42+
<!-- usage:start -->
43+
44+
## Usage
45+
46+
```yaml
47+
name: Release
48+
49+
on:
50+
release:
51+
types: [published]
52+
53+
permissions: {}
54+
55+
jobs:
56+
release:
57+
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
58+
permissions:
59+
contents: read
60+
packages: write
61+
id-token: write
62+
secrets:
63+
# Authentication token for the registry.
64+
# For npm: Use an npm access token with publish permissions.
65+
# For GitHub Packages: Use `GITHUB_TOKEN` or a PAT with `packages:write` permission.
66+
registry-token: ${{ secrets.NPM_TOKEN }}
67+
68+
# Secrets to be used during the build step (optional).
69+
build-secrets: ""
70+
with:
71+
# JSON array of runner(s) to use.
72+
# Default: `["ubuntu-latest"]`
73+
runs-on: '["ubuntu-latest"]'
74+
75+
# Build parameters. Set to empty string to disable.
76+
# Default: `build`
77+
build: build
78+
79+
# Documentation generation parameters.
80+
# Set to empty string or `false` to disable.
81+
docs: ""
82+
83+
# Registry configuration.
84+
# Use `npm`, `github`, or a URL/JSON object.
85+
# Default: `npm`
86+
registry: npm
87+
88+
# Command to run for publishing.
89+
# Default: `publish`
90+
publish-command: publish
91+
92+
# npm distribution tag.
93+
# Default: `latest`
94+
tag: latest
95+
96+
# Whether to perform a dry run.
97+
# Default: `false`
98+
dry-run: false
99+
100+
# Whether to generate provenance attestation.
101+
# Default: `true`
102+
provenance: true
103+
104+
# Working directory where the package is located.
105+
# Default: `.`
106+
working-directory: .
107+
```
108+
109+
<!-- usage:end -->
110+
111+
<!-- markdownlint-disable MD013 -->
112+
113+
<!-- inputs:start -->
114+
115+
## Inputs
116+
117+
### Workflow Call Inputs
118+
119+
| **Input** | **Description** | **Required** | **Type** | **Default** |
120+
| ----------------------- | ---------------------------------------------------------------------------------- | ------------ | ----------- | ------------------- |
121+
| **`runs-on`** | JSON array of runner(s) to use. | **false** | **string** | `["ubuntu-latest"]` |
122+
| | See <https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job>. | | | |
123+
| **`build`** | Build parameters. Must be a string or a JSON object. | **false** | **string** | `build` |
124+
| | Set to empty string to disable build step. | | | |
125+
| | For string, provide a list of commands to run during the build step, one per line. | | | |
126+
| | For JSON object, provide `commands` array and optional `env` object. | | | |
127+
| **`docs`** | Documentation generation parameters. | **false** | **string** | - |
128+
| | Set to empty string or `false` to disable. | | | |
129+
| | Set to `true` for default command (`docs`). | | | |
130+
| | Accepts JSON object with `command`, `output`, and `artifact` properties. | | | |
131+
| **`registry`** | Registry configuration for package publishing. | **false** | **string** | `npm` |
132+
| | Supported values: `npm`, `github`, URL, or JSON object with `url` and `scope`. | | | |
133+
| **`publish-command`** | Command to run for publishing the package. | **false** | **string** | `publish` |
134+
| | Defaults to `publish` which runs `npm publish` or equivalent. | | | |
135+
| **`tag`** | npm distribution tag for the published package. | **false** | **string** | `latest` |
136+
| | Common values: `latest`, `next`, `canary`. | | | |
137+
| **`dry-run`** | Whether to perform a dry run (no actual publish). | **false** | **boolean** | `false` |
138+
| **`provenance`** | Whether to generate provenance attestation for the published package. | **false** | **boolean** | `true` |
139+
| | Requires npm 9.5.0+ and appropriate permissions. | | | |
140+
| **`working-directory`** | Working directory where the package is located. | **false** | **string** | `.` |
141+
142+
<!-- inputs:end -->
143+
144+
<!-- markdownlint-enable MD013 -->
145+
146+
<!-- secrets:start -->
147+
148+
## Secrets
149+
150+
| **Secret** | **Description** | **Required** |
151+
| -------------------- | ---------------------------------------------------------------------------------- | ------------ |
152+
| **`registry-token`** | Authentication token for the registry. | **true** |
153+
| | For npm: Use an npm access token with publish permissions. | |
154+
| | For GitHub Packages: Use `GITHUB_TOKEN` or a PAT with `packages:write` permission. | |
155+
| **`build-secrets`** | Secrets to be used during the build step. | **false** |
156+
| | Must be a multi-line env formatted string. | |
157+
158+
<!-- secrets:end -->
159+
160+
<!-- outputs:start -->
161+
162+
## Outputs
163+
164+
| **Output** | **Description** |
165+
| ---------------------- | ----------------------------------------------- |
166+
| **`version`** | The version of the published package. |
167+
| **`package-name`** | The name of the published package. |
168+
| **`docs-artifact-id`** | ID of the documentation artifact (if uploaded). |
169+
170+
<!-- outputs:end -->
171+
172+
<!-- examples:start -->
173+
174+
## Examples
175+
176+
### Basic Release to npm
177+
178+
```yaml
179+
name: Release to npm
180+
181+
on:
182+
release:
183+
types: [published]
184+
185+
permissions: {}
186+
187+
jobs:
188+
release:
189+
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
190+
permissions:
191+
contents: read
192+
packages: write
193+
id-token: write
194+
secrets:
195+
registry-token: ${{ secrets.NPM_TOKEN }}
196+
```
197+
198+
### Release to GitHub Packages
199+
200+
```yaml
201+
name: Release to GitHub Packages
202+
203+
on:
204+
release:
205+
types: [published]
206+
207+
permissions: {}
208+
209+
jobs:
210+
release:
211+
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
212+
permissions:
213+
contents: read
214+
packages: write
215+
id-token: write
216+
secrets:
217+
registry-token: ${{ secrets.GITHUB_TOKEN }}
218+
with:
219+
registry: github
220+
provenance: false
221+
```
222+
223+
### Release with Documentation
224+
225+
```yaml
226+
name: Release with Documentation
227+
228+
on:
229+
release:
230+
types: [published]
231+
232+
permissions: {}
233+
234+
jobs:
235+
release:
236+
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
237+
permissions:
238+
contents: read
239+
packages: write
240+
id-token: write
241+
secrets:
242+
registry-token: ${{ secrets.NPM_TOKEN }}
243+
with:
244+
docs: |
245+
{
246+
"command": "build:docs",
247+
"output": "docs-dist",
248+
"artifact": true
249+
}
250+
```
251+
252+
### Prerelease with Next Tag
253+
254+
```yaml
255+
name: Pre-release
256+
257+
on:
258+
release:
259+
types: [prereleased]
260+
261+
permissions: {}
262+
263+
jobs:
264+
release:
265+
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
266+
permissions:
267+
contents: read
268+
packages: write
269+
id-token: write
270+
secrets:
271+
registry-token: ${{ secrets.NPM_TOKEN }}
272+
with:
273+
tag: next
274+
```
275+
276+
### Custom Registry
277+
278+
```yaml
279+
name: Release to Custom Registry
280+
281+
on:
282+
release:
283+
types: [published]
284+
285+
permissions: {}
286+
287+
jobs:
288+
release:
289+
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
290+
permissions:
291+
contents: read
292+
packages: write
293+
id-token: write
294+
secrets:
295+
registry-token: ${{ secrets.CUSTOM_REGISTRY_TOKEN }}
296+
with:
297+
registry: |
298+
{
299+
"url": "https://my-registry.example.com",
300+
"scope": "@myorg"
301+
}
302+
provenance: false
303+
```
304+
305+
### Dry Run for Testing
306+
307+
```yaml
308+
name: Test Release
309+
310+
on:
311+
workflow_dispatch:
312+
313+
permissions: {}
314+
315+
jobs:
316+
test-release:
317+
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
318+
permissions:
319+
contents: read
320+
packages: write
321+
id-token: write
322+
secrets:
323+
registry-token: ${{ secrets.NPM_TOKEN }}
324+
with:
325+
dry-run: true
326+
```
327+
328+
### Monorepo Package Release
329+
330+
```yaml
331+
name: Release Package
332+
333+
on:
334+
release:
335+
types: [published]
336+
337+
permissions: {}
338+
339+
jobs:
340+
release:
341+
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
342+
permissions:
343+
contents: read
344+
packages: write
345+
id-token: write
346+
secrets:
347+
registry-token: ${{ secrets.NPM_TOKEN }}
348+
with:
349+
working-directory: packages/my-package
350+
build: |
351+
{
352+
"commands": ["build"],
353+
"env": {
354+
"NODE_ENV": "production"
355+
}
356+
}
357+
```
358+
359+
<!-- examples:end -->
360+
361+
<!-- contributing:start -->
362+
363+
## Contributing
364+
365+
Contributions are welcome! Please see the [contributing guidelines](https://github.com/hoverkraft-tech/ci-github-nodejs/blob/main/CONTRIBUTING.md) for more details.
366+
367+
<!-- contributing:end -->
368+
369+
<!-- security:start -->
370+
<!-- security:end -->
371+
372+
<!-- license:start -->
373+
374+
## License
375+
376+
This project is licensed under the MIT License.
377+
378+
SPDX-License-Identifier: MIT
379+
380+
Copyright © 2025 hoverkraft-tech
381+
382+
For more details, see the [license](http://choosealicense.com/licenses/mit/).
383+
384+
<!-- license:end -->

0 commit comments

Comments
 (0)