Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
60 changes: 21 additions & 39 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,42 +2,21 @@ name: Publish packages to npm

on:
push:
branches:
- "v*"
- "v*-dev"
tags:
- "v*.*.*"

permissions:
contents: write
id-token: write
contents: read

jobs:
credentials:
name: Verify npm publishing credentials
if: startsWith(github.ref, 'refs/heads/')
runs-on: ubuntu-latest
environment: Publish
steps:
- uses: actions/setup-node@v4
with:
node-version: "24"
registry-url: "https://registry.npmjs.org"
- name: Require and validate the repository-owned npm token
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
if [ -z "$NODE_AUTH_TOKEN" ]; then
echo "NPM_TOKEN is not available to the Publish environment." >&2
exit 1
fi
npm whoami

publish:
name: Publish coordinated package set
if: startsWith(github.ref, 'refs/tags/')
runs-on: ubuntu-latest
environment: Publish
permissions:
contents: write
id-token: write
concurrency:
group: npm-${{ github.ref }}
cancel-in-progress: false
Expand All @@ -51,17 +30,21 @@ jobs:
with:
node-version: "24"
registry-url: "https://registry.npmjs.org"
cache: npm

- name: Require repository-owned npm credentials
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
# Each npm package trusts this repository, publish.yml, and Publish environment.
# OIDC authentication occurs during npm publish, not npm whoami.
- name: Verify trusted publishing support
run: |
if [ -z "$NODE_AUTH_TOKEN" ]; then
echo "NPM_TOKEN is not available to the Publish environment." >&2
exit 1
fi
npm whoami
node --input-type=module -e '
import { execFileSync } from "node:child_process";
const version = execFileSync("npm", ["--version"], { encoding: "utf8" }).trim();
const [major, minor, patch] = version.split(".").map(Number);
if (!(major > 11 || (major === 11 && (minor > 5 || (minor === 5 && patch >= 1))))) {
throw new Error("Trusted publishing requires npm >= 11.5.1; found " + version);
}
'
test -n "$ACTIONS_ID_TOKEN_REQUEST_URL"
test -n "$ACTIONS_ID_TOKEN_REQUEST_TOKEN"

- name: Verify tag, package set, and owning branch
run: |
Expand Down Expand Up @@ -100,8 +83,6 @@ jobs:
done

- name: Publish all packages
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
version="${GITHUB_REF_NAME#v}"
dist_tag="$(node -e "import('./scripts/release-policy.mjs').then(m => console.log(m.parseReleaseVersion(process.argv[1]).distTag))" "$version")"
Expand All @@ -121,16 +102,17 @@ jobs:
@genlayer/transaction-kit \
@genlayer/transaction-kit-react \
@genlayer/transaction-kit-vue; do
for attempt in 1 2 3 4 5 6; do
# npm publish-time scanning can delay public availability by minutes.
for attempt in $(seq 1 60); do
published="$(npm view "$package_name@$version" version 2>/dev/null || true)"
if [ "$published" = "$version" ]; then
break
fi
if [ "$attempt" -eq 6 ]; then
if [ "$attempt" -eq 60 ]; then
echo "$package_name@$version was not visible after publication." >&2
exit 1
fi
sleep 5
sleep 10
done
done

Expand Down
52 changes: 52 additions & 0 deletions docs/publishing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Publishing

The tag-triggered `.github/workflows/publish.yml` uses npm trusted publishing
(GitHub Actions OIDC). It does not read `NPM_TOKEN`. Branch pushes run ordinary CI,
not an npm credential check. Publishing still requires the tag to match the
owning release branch's current head and all package versions to agree.

## npm configuration

Configure a GitHub Actions trusted publisher separately for each package:

- `@genlayer/transaction-kit`
- `@genlayer/transaction-kit-react`
- `@genlayer/transaction-kit-vue`

Use these exact, case-sensitive values:

| Field | Value |
| --- | --- |
| Organization or user | `genlayerlabs` |
| Repository | `genlayer-transaction-kit` |
| Workflow filename | `publish.yml` |
| Environment name | `Publish` |
| Allowed actions | Enable `npm publish` (staging is also allowed by npm) |

The workflow uses GitHub-hosted runners with Node 24, verifies npm >= 11.5.1,
and grants `id-token: write` only to the publishing job. `npm whoami` is not an
OIDC test: authentication is performed by `npm publish` itself.

## Migration and verification

1. Save and verify all three npm trusted publisher connections before landing
the tokenless workflow.
2. Validate the workflow and normal build/test gates. A dry run or a rerun that
skips existing versions does **not** prove OIDC publication works.
3. Verify the next authorized release publishes all three packages without a
token and has the expected version, `gitHead`, dist-tag, and provenance.
Do not create a release solely as an authentication probe.
4. After a successful tokenless release, remove the obsolete `NPM_TOKEN` secret
from the GitHub `Publish` environment, revoke its npm token, and select
"Require two-factor authentication and disallow bypass 2fa tokens" for all
three packages. Keep any unrelated credentials unchanged.

npm scans uploads before making them publicly available. Registry verification
allows up to ten minutes per package; a timeout does not mean the upload failed.
Check registry availability before retrying. Existing versions are skipped only
when their `gitHead` matches the release commit.

If a trusted connection is misconfigured, correct it in npm before retrying the
same release. Never move a published release tag or overwrite a package version.

Reference: <https://docs.npmjs.com/trusted-publishers/>
28 changes: 28 additions & 0 deletions scripts/publish-workflow.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import test from 'node:test';

const workflow = readFileSync(new URL('../.github/workflows/publish.yml', import.meta.url), 'utf8');

test('publishing uses GitHub OIDC without a long-lived npm credential', () => {
assert.match(workflow, /id-token: write/);
assert.match(workflow, /environment: Publish/);
assert.match(workflow, /runs-on: ubuntu-latest/);
assert.doesNotMatch(workflow, /secrets\.NPM_TOKEN|NODE_AUTH_TOKEN/);
assert.match(workflow, /Trusted publishing requires npm >= 11\.5\.1/);
assert.match(workflow, /test -n "\$ACTIONS_ID_TOKEN_REQUEST_URL"/);
});

test('publication remains tag-only and retains release safety checks', () => {
assert.doesNotMatch(workflow, /branches:|workflow_dispatch:/);
assert.match(workflow, /startsWith\(github.ref, 'refs\/tags\/'\)/);
assert.match(workflow, /not the current head of \$branch; refusing to publish/);
assert.match(workflow, /npm publish --workspace "\$workspace" --tag "\$dist_tag" --provenance --access public/);
assert.match(workflow, /published_sha.*\$GITHUB_SHA/);
});

test('registry verification tolerates npm publish-time scanning', () => {
assert.match(workflow, /seq 1 60/);
assert.match(workflow, /sleep 10/);
assert.match(workflow, /was not visible after publication/);
});
Loading