From dc333db4cf51370ce902f700854436d3a3f687ae Mon Sep 17 00:00:00 2001 From: Edgars Date: Wed, 9 Sep 2026 11:40:41 +0100 Subject: [PATCH] ci: migrate npm releases to trusted publishing Use package-scoped GitHub OIDC trust in the Publish environment instead of an expiring personal token. Preserve tag ownership and provenance checks, validate npm support, and tolerate publish-time registry scanning. Document staged credential retirement after a real tokenless release. --- .github/workflows/publish.yml | 60 +++++++++++-------------------- docs/publishing.md | 52 +++++++++++++++++++++++++++ scripts/publish-workflow.test.mjs | 28 +++++++++++++++ 3 files changed, 101 insertions(+), 39 deletions(-) create mode 100644 docs/publishing.md create mode 100644 scripts/publish-workflow.test.mjs diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index fabb918..3095f14 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -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 @@ -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: | @@ -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")" @@ -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 diff --git a/docs/publishing.md b/docs/publishing.md new file mode 100644 index 0000000..6808771 --- /dev/null +++ b/docs/publishing.md @@ -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: diff --git a/scripts/publish-workflow.test.mjs b/scripts/publish-workflow.test.mjs new file mode 100644 index 0000000..08aa723 --- /dev/null +++ b/scripts/publish-workflow.test.mjs @@ -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/); +});