Skip to content

docs: update actions and workflows documentation #463

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hoverkraft-bot merged 1 commit into from
May 14, 2026
+92 −60
Merged

docs: update actions and workflows documentation #463

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 73 additions & 40 deletions .github/workflows/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# GitHub Reusable Workflow: Node.js Release

<div align="center">
<img src="https://opengraph.githubassets.com/0e54b99e7f052e2a353659bcb048b76224cb355f919e9772252049df8eec3976/hoverkraft-tech/ci-github-nodejs" width="60px" align="center" alt="Node.js Release" />
<img src="https://opengraph.githubassets.com/5d627588970f22174162eefe5c3159eb3bdc271c25b77ec0286fa7fb33c9a2f9/hoverkraft-tech/ci-github-nodejs" width="60px" align="center" alt="Node.js Release" />
</div>

---
Expand All @@ -23,17 +23,12 @@

## Overview

Workflow to publish the exact Node.js package tarball produced and verified by
CI.

The workflow downloads a raw `.tgz` artifact by immutable artifact ID, verifies
that exactly one tarball is present, configures Node.js for the target registry,
and runs `npm publish` against that tarball.
Workflow to release Node.js packages from a package tarball produced by CI.

### Permissions

- **`contents`**: `read`
- **`id-token`**: `write` (required for provenance)
- **`id-token`**: `write`
- **`packages`**: `write`

<!-- overview:end -->
Expand All @@ -42,37 +37,60 @@ and runs `npm publish` against that tarball.

## Usage

### Publish a CI Package Tarball

```yaml
name: Release

name: Node.js Release
on:
push:
tags: ["*"]

branches:
- main
permissions: {}

jobs:
ci:
uses: ./.github/workflows/__shared-ci.yml
permissions:
contents: read
id-token: write
packages: read
secrets: inherit

release:
needs: ci
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
permissions:
contents: read
packages: write
id-token: write
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@47891dc49a31209a88949e081d97a010f8cd20c4 # 0.23.2
permissions: {}
secrets:
registry-token: ${{ secrets.NPM_TOKEN }}
# GitHub token to use for authentication.
# Defaults to `GITHUB_TOKEN` if not provided.
github-token: ""

# Authentication token for the package registry.
registry-token: ""
with:
package-tarball-artifact-id: ${{ needs.ci.outputs.package-tarball-artifact-id }}
# JSON array of runner(s) to use.
# See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job.
#
# Default: `["ubuntu-latest"]`
runs-on: '["ubuntu-latest"]'

# Artifact ID of the package tarball produced by CI.
# This input is required.
package-tarball-artifact-id: ""

# Registry URL used by npm publish.
# Default: `https://registry.npmjs.org`
registry-url: https://registry.npmjs.org

# Package access level passed to npm publish. Leave empty to use npm defaults.
# Default: `public`
access: public

# npm distribution tag for the published package.
# Common values:
# - `latest` — Default tag for stable releases
# - `next` — Pre-release or beta versions
# - `canary` — Canary/nightly builds
#
# See https://docs.npmjs.com/adding-dist-tags-to-packages.
#
# Default: `latest`
tag: latest

# Whether to generate npm provenance for npmjs.org publishes.
# Default: `true`
provenance: true

# Whether to run npm publish without publishing the package.
dry-run: false
```

<!-- usage:end -->
Expand All @@ -91,10 +109,14 @@ jobs:
| | See <https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job>. | | | |
| **`package-tarball-artifact-id`** | Artifact ID of the package tarball produced by CI. | **true** | **string** | - |
| **`registry-url`** | Registry URL used by npm publish. | **false** | **string** | `https://registry.npmjs.org` |
| **`access`** | Package access level passed to npm publish. | **false** | **string** | `public` |
| | Leave empty to use npm defaults. | | | |
| **`access`** | Package access level passed to npm publish. Leave empty to use npm defaults. | **false** | **string** | `public` |
| **`tag`** | npm distribution tag for the published package. | **false** | **string** | `latest` |
| | Common values: `latest`, `next`, `canary`. | | | |
| | Common values: | | | |
| | - `latest` — Default tag for stable releases | | | |
| | - `next` — Pre-release or beta versions | | | |
| | - `canary` — Canary/nightly builds | | | |
| | | | | |
| | See <https://docs.npmjs.com/adding-dist-tags-to-packages>. | | | |
| **`provenance`** | Whether to generate npm provenance for npmjs.org publishes. | **false** | **boolean** | `true` |
| **`dry-run`** | Whether to run npm publish without publishing the package. | **false** | **boolean** | `false` |

Expand All @@ -106,9 +128,11 @@ jobs:

## Secrets

| **Secret** | **Description** | **Required** |
| -------------------- | --------------------------------------------------------- | ------------ |
| **`registry-token`** | Authentication token for token-based registry publishing. | **false** |
| **Secret** | **Description** | **Required** |
| -------------------- | ---------------------------------------------- | ------------ |
| **`github-token`** | GitHub token to use for authentication. | **false** |
| | Defaults to `GITHUB_TOKEN` if not provided. | |
| **`registry-token`** | Authentication token for the package registry. | **false** |

<!-- secrets:end -->

Expand Down Expand Up @@ -138,7 +162,7 @@ jobs:

release:
needs: ci
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@47891dc49a31209a88949e081d97a010f8cd20c4 # 0.23.2
permissions:
contents: read
packages: write
Expand Down Expand Up @@ -166,7 +190,7 @@ permissions: {}

jobs:
dry-run:
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@47891dc49a31209a88949e081d97a010f8cd20c4 # 0.23.2
permissions:
contents: read
packages: write
Expand Down Expand Up @@ -198,8 +222,17 @@ This project is licensed under the MIT License.

SPDX-License-Identifier: MIT

Copyright © 2025 hoverkraft-tech
Copyright © 2026 hoverkraft-tech

For more details, see the [license](http://choosealicense.com/licenses/mit/).

<!-- license:end -->
<!-- outputs:start -->
<!-- outputs:end -->
<!-- generated:start -->

---

This documentation was automatically generated by [CI Dokumentor](https://github.com/hoverkraft-tech/ci-dokumentor).

<!-- generated:end -->
39 changes: 19 additions & 20 deletions actions/package/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# ![Icon](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGNsYXNzPSJmZWF0aGVyIGZlYXRoZXItcGFja2FnZSIgY29sb3I9ImJsdWUiPjxsaW5lIHgxPSIxNi41IiB5MT0iOS40IiB4Mj0iNy41IiB5Mj0iNC4yMSI+PC9saW5lPjxwYXRoIGQ9Ik0yMSAxNlY4YTIgMiAwIDAgMC0xLTEuNzNsLTctNGEyIDIgMCAwIDAtMiAwbC03IDRBMiAyIDAgMCAwIDMgOHY4YTIgMiAwIDAgMCAxIDEuNzNsNyA0YTIgMiAwIDAgMCAyIDBsNy00QTIgMiAwIDAgMCAyMSAxNnoiPjwvcGF0aD48cG9seWxpbmUgcG9pbnRzPSIzLjI3IDYuOTYgMTIgMTIuMDEgMjAuNzMgNi45NiI+PC9wb2x5bGluZT48bGluZSB4MT0iMTIiIHkxPSIyMi4wOCIgeDI9IjEyIiB5Mj0iMTIiPjwvbGluZT48L3N2Zz4=) GitHub Action: Package

<div align="center">
<img src="https://opengraph.githubassets.com/5cfdb085d41e25a10008bde097bb5b24d2c4f7dbb5717e118dc85afcb98bcadd/hoverkraft-tech/ci-github-nodejs" width="60px" align="center" alt="Package" />
<img src="https://opengraph.githubassets.com/5d627588970f22174162eefe5c3159eb3bdc271c25b77ec0286fa7fb33c9a2f9/hoverkraft-tech/ci-github-nodejs" width="60px" align="center" alt="Package" />
</div>

---
Expand All @@ -30,7 +30,7 @@ Action to create and upload an npm package tarball from a Node.js project
## Usage

```yaml
- uses: hoverkraft-tech/ci-github-nodejs/actions/package@9d465a03741b287db18b242e0ec46990888cc6a3 # 0.23.0
- uses: hoverkraft-tech/ci-github-nodejs/actions/package@47891dc49a31209a88949e081d97a010f8cd20c4 # 0.23.2
with:
# Working directory where dependencies are installed for packaging.
# Can be absolute or relative to the repository root.
Expand All @@ -57,30 +57,29 @@ Action to create and upload an npm package tarball from a Node.js project
# The version is applied without creating a Git tag.
version: ""

# Optional name of the uploaded package tarball artifact.
# When omitted, a unique `package-tarball-*` name is generated.
artifact-name: package-tarball
# Name of the uploaded package tarball artifact
artifact-name: ""
```

<!-- usage:end -->
<!-- inputs:start -->

## Inputs

| **Input** | **Description** | **Required** | **Default** |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------------ | -------------------------- |
| **`working-directory`** | Working directory where dependencies are installed for packaging. | **false** | `.` |
| | Can be absolute or relative to the repository root. | | |
| **`package-directory`** | Optional package directory to version and pack. | **false** | - |
| | Can be absolute or relative to `working-directory`. | | |
| | Useful for monorepos where dependencies are installed at the root. | | |
| **`build-artifact-id`** | Optional build artifact ID to download before packaging. | **false** | - |
| | When provided, the artifact will be downloaded to the workspace. | | |
| **`build-artifact-path`** | Optional path to the build artifact contents relative to the workspace root. | **false** | `${{ github.workspace }}` |
| | Used to locate the files to be included in the package when a build artifact is downloaded. | | |
| **`version`** | Optional version to apply with `npm version` before packaging. | **false** | - |
| | The version is applied without creating a Git tag. | | |
| **`artifact-name`** | Name of the uploaded package tarball artifact | **false** | Auto-generated unique name |
| **Input** | **Description** | **Required** | **Default** |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------------ | ------------------------- |
| **`working-directory`** | Working directory where dependencies are installed for packaging. | **false** | `.` |
| | Can be absolute or relative to the repository root. | | |
| **`package-directory`** | Optional package directory to version and pack. | **false** | - |
| | Can be absolute or relative to `working-directory`. | | |
| | Useful for monorepos where dependencies are installed at the root. | | |
| **`build-artifact-id`** | Optional build artifact ID to download before packaging. | **false** | - |
| | When provided, the artifact will be downloaded to the workspace. | | |
| **`build-artifact-path`** | Optional path to the build artifact contents relative to the workspace root. | **false** | `${{ github.workspace }}` |
| | Used to locate the files to be included in the package when a build artifact is downloaded. | | |
| **`version`** | Optional version to apply with `npm version` before packaging. | **false** | - |
| | The version is applied without creating a Git tag. | | |
| **`artifact-name`** | Name of the uploaded package tarball artifact | **false** | - |

<!-- inputs:end -->
<!-- secrets:start -->
Expand All @@ -107,7 +106,7 @@ jobs:
package-tarball-artifact-id: ${{ steps.package.outputs.package-tarball-artifact-id }}
steps:
- id: package
uses: hoverkraft-tech/ci-github-nodejs/actions/package@9d465a03741b287db18b242e0ec46990888cc6a3 # 0.23.0
uses: hoverkraft-tech/ci-github-nodejs/actions/package@47891dc49a31209a88949e081d97a010f8cd20c4 # 0.23.2

consume:
needs: package
Expand Down