feat: publish to public npm via trusted publishing

.changeset/config.json

@@ -31,7 +31,7 @@
       "@openchoreo/backstage-portal-backend"
     ]
   ],
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": ["app", "backend"]

.changeset/publish-to-public-npm.md

@@ -0,0 +1,5 @@
+---
+'@openchoreo/backstage-plugin': patch
+---
+
+Publish `@openchoreo/*` to the public npm registry instead of GitHub Packages. Installing the plugins no longer requires a GitHub personal access token or any registry configuration. Releases are published from CI via npm trusted publishing (OIDC), so every version from this release onward carries a signed provenance attestation.

.github/workflows/release.yml

@@ -13,49 +13,73 @@ env:
   IMAGE_NAME: openchoreo/openchoreo-ui
 
 jobs:
-  release:
-    name: Release
+  # npm publish runs before any Docker retag so a publish failure aborts the
+  # release before GHCR is mutated. The reverse ordering would leave the image
+  # retagged to vX.Y.Z (and possibly `latest`) without the corresponding
+  # @openchoreo/* packages on the npm registry.
+  publish-npm:
+    name: Publish to npm
     runs-on: ubuntu-24.04
+    # Bound to a protected environment with required reviewers. npm matches the
+    # OIDC claim against repository + workflow filename + THIS environment name,
+    # so renaming it here also requires updating every package's trusted
+    # publisher (`npm trust github @openchoreo/<pkg> --environment ...`).
+    environment: npm-publish
     permissions:
-      packages: write
+      contents: read
+      # Mints the OIDC token that npm exchanges for a short-lived publish
+      # credential (trusted publishing) and that signs the provenance
+      # attestation. No npm token exists anywhere in this workflow.
+      id-token: write
+    outputs:
+      release-tag: ${{ steps.release-vars.outputs.release-tag }}
+      git-sha-short: ${{ steps.release-vars.outputs.git-sha-short }}
+      is-prerelease: ${{ steps.release-vars.outputs.is-prerelease }}
+      latest: ${{ steps.release-vars.outputs.latest }}
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set commit SHA and release tag
+      - name: Resolve release variables
+        id: release-vars
         run: |
-          echo "GIT_SHA_SHORT=$(git rev-parse --short=8 HEAD)" >> $GITHUB_ENV
+          git fetch --tags --force
+          GIT_SHA_SHORT=$(git rev-parse --short=8 HEAD)
           RELEASE_TAG=${GITHUB_REF##*/}
-          echo "RELEASE_TAG=${RELEASE_TAG}" >> $GITHUB_ENV
+
           # Detect prerelease versions (SemVer tags containing a hyphen, e.g., v1.0.0-rc.1)
           if [[ "${RELEASE_TAG}" == *-* ]]; then
-            echo "IS_PRERELEASE=true" >> $GITHUB_ENV
+            IS_PRERELEASE=true
           else
-            echo "IS_PRERELEASE=false" >> $GITHUB_ENV
+            IS_PRERELEASE=false
           fi
 
-      - name: Set latest flag
-        run: |
-          git fetch --tags --force
           latest_tag=$(git tag -l | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)
           if [ "$latest_tag" == "${RELEASE_TAG}" ]; then
-            echo "LATEST=true" >> $GITHUB_ENV
+            LATEST=true
           else
-            echo "LATEST=false" >> $GITHUB_ENV
+            LATEST=false
           fi
 
-      # npm publish runs before any Docker retag so a publish failure aborts
-      # the release before GHCR is mutated. The reverse ordering would leave
-      # the image retagged to vX.Y.Z (and possibly `latest`) without the
-      # corresponding @openchoreo/* packages on the npm registry.
+          {
+            echo "release-tag=${RELEASE_TAG}"
+            echo "git-sha-short=${GIT_SHA_SHORT}"
+            echo "is-prerelease=${IS_PRERELEASE}"
+            echo "latest=${LATEST}"
+          } >> $GITHUB_OUTPUT
+
+          echo "RELEASE_TAG=${RELEASE_TAG}" >> $GITHUB_ENV
+          echo "IS_PRERELEASE=${IS_PRERELEASE}" >> $GITHUB_ENV
+          echo "LATEST=${LATEST}" >> $GITHUB_ENV
 
       - name: Setup Node.js
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: 22
           cache: 'yarn'
           # Intentionally no `registry-url:` — Yarn Berry ignores the .npmrc
-          # this would write. Auth is wired via YARN_NPM_AUTH_TOKEN below.
+          # this would write. The publish registry comes from
+          # `npmPublishRegistry` in .yarnrc.yml, and auth comes from OIDC.
 
       - name: Install dependencies
         run: yarn install --immutable
@@ -77,12 +101,17 @@ jobs:
         # exists before prepack reads it.
         run: yarn build:all
 
-      - name: Publish to GitHub Packages
+      - name: Publish to npm
+        # Auth is npm trusted publishing (OIDC) — there is deliberately no
+        # NPM_TOKEN / YARN_NPM_AUTH_TOKEN here. Yarn detects the GitHub Actions
+        # OIDC environment and exchanges the id-token for a short-lived
+        # registry credential (requires Yarn >= 4.10).
+        #
         # Dist-tag scheme: `latest` only for the highest stable version,
         # `next` for prereleases, `release-X.Y` for back-line patches so a
         # re-release of an older line never steals `latest` from a newer one.
         env:
-          YARN_NPM_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          YARN_NPM_PUBLISH_PROVENANCE: 'true'
         run: |
           TAG=latest
           if [ "${IS_PRERELEASE}" = "true" ]; then
@@ -94,6 +123,18 @@ jobs:
           yarn workspaces foreach --all --no-private --topological --verbose \
             npm publish --tolerate-republish --access public --tag "${TAG}"
 
+  retag-image:
+    name: Retag release image
+    needs: publish-npm
+    runs-on: ubuntu-24.04
+    permissions:
+      packages: write
+    env:
+      RELEASE_TAG: ${{ needs.publish-npm.outputs.release-tag }}
+      GIT_SHA_SHORT: ${{ needs.publish-npm.outputs.git-sha-short }}
+      IS_PRERELEASE: ${{ needs.publish-npm.outputs.is-prerelease }}
+      LATEST: ${{ needs.publish-npm.outputs.latest }}
+    steps:
       - name: Login to GitHub container registry
         uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
         with:

.npmrc

@@ -2,5 +2,3 @@
 # Only enable scripts for trusted, vetted packages when absolutely necessary
 # See: https://docs.npmjs.com/cli/v10/using-npm/scripts#life-cycle-scripts
 ignore-scripts=true
-//npm.pkg.github.com/:_authToken=${YARN_NPM_AUTH_TOKEN}
-@openchoreo:registry=https://npm.pkg.github.com

.yarnrc.yml

@@ -1,3 +1,12 @@
+approvedGitRepositories:
+  - '**'
+
+enableScripts: true
+
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-4.4.1.cjs
+npmMinimalAgeGate: 0
+
+npmPublishRegistry: 'https://registry.npmjs.org'
+
+yarnPath: .yarn/releases/yarn-4.18.0.cjs

CONTRIBUTING.md

@@ -103,7 +103,14 @@ The `Changeset Check` workflow ([`.github/workflows/changeset-check.yml`](.githu
 
 ## Releasing
 
-Releases are tag-driven. Pushing a `v*.*.*` tag triggers the [release workflow](.github/workflows/release.yml), which retags the Docker image in GHCR **and** publishes every public `@openchoreo/*` package to GitHub Packages (`https://npm.pkg.github.com`). Authentication uses the auto-issued `GITHUB_TOKEN` — no extra secrets needed.
+Releases are tag-driven. Pushing a `v*.*.*` tag triggers the [release workflow](.github/workflows/release.yml), which publishes every public `@openchoreo/*` package to the **public npm registry** and then retags the Docker image in GHCR.
+
+**There are no publish secrets.** Authentication is [npm trusted publishing](https://docs.npmjs.com/trusted-publishers): the workflow mints a short-lived OIDC token (`id-token: write`) that npm exchanges for a publish credential. npm only accepts it from `openchoreo/backstage-plugins`, from `release.yml`, in the `npm-publish` environment — a trusted publisher is configured per package with those exact claims. As a side effect every published version gets a signed [provenance attestation](https://docs.npmjs.com/generating-provenance-statements).
+
+Two consequences worth knowing:
+
+- **Renaming `release.yml`, or the `npm-publish` environment, breaks publishing** until every package's trusted publisher is reconfigured (`npm trust github @openchoreo/<pkg> --repository openchoreo/backstage-plugins --file release.yml --environment npm-publish --allow-publish`). npm does not validate the config when it is saved, and a mismatch surfaces as a misleading `404` on publish, not an auth error.
+- **Publishing requires Yarn >= 4.10**, which is where `yarn npm publish` learned the OIDC exchange. Do not downgrade the pinned Yarn version.
 
 ### Cutting a release
 
@@ -131,26 +138,47 @@ Releases are tag-driven. Pushing a `v*.*.*` tag triggers the [release workflow](
    git push origin v0.4.0
    ```
 
-5. **CI publishes**. The release workflow:
-   - Retags the existing Docker image (built earlier on the `main` push) to `vX.Y.Z` in GHCR.
-   - Runs `yarn install --immutable && yarn tsc && yarn build:all`, then `yarn workspaces foreach --all --no-private --topological --verbose npm publish --tolerate-republish --access public --tag <latest|next>` to publish npm packages to GitHub Packages.
+5. **Approve the publish**. The `publish-npm` job targets the protected `npm-publish` environment and waits in _Waiting_ until a required reviewer approves it from the workflow run page. Nothing is published — and no OIDC token is minted — before that approval.
+
+6. **CI publishes**. The release workflow:
+   - `publish-npm`: runs `yarn install --immutable && yarn tsc && yarn build:all`, then `yarn workspaces foreach --all --no-private --topological --verbose npm publish --tolerate-republish --access public --tag <latest|next|release-X.Y>`.
+   - `retag-image`: only after `publish-npm` succeeds, retags the existing Docker image (built earlier on the `main` push) to `vX.Y.Z` in GHCR. Ordering matters — a failed publish must not leave a `vX.Y.Z` image without the matching packages.
    - On **stable** tags (`vX.Y.Z`) publishes under the `latest` npm dist-tag.
    - On **prerelease** tags (`vX.Y.Z-rc.N`, `vX.Y.Z-test.N`, etc. — any tag containing a hyphen) publishes under the `next` dist-tag, leaving `latest` untouched.
+   - On a **back-line** stable tag (a `vX.Y.Z` that is not the highest stable tag) publishes under `release-X.Y`, so re-releasing an older line never steals `latest` from a newer one.
 
 `yarn npm publish` (not `npm publish` or `changeset publish`) is required so that Yarn Berry rewrites `workspace:^` deps to concrete versions at pack time. `npm publish` and `changeset publish` (which shells out to `npm publish` on non-pnpm repos) leak `workspace:^` strings into the tarball and break installs for external consumers.
 
 ### Verifying a release
 
 ```bash
-yarn npm info @openchoreo/backstage-plugin --registry=https://npm.pkg.github.com
-yarn npm info @openchoreo/backstage-design-system --registry=https://npm.pkg.github.com
+yarn npm info @openchoreo/backstage-plugin
+yarn npm info @openchoreo/backstage-design-system
 ```
 
 Both should show the new version. Confirm under `dist-tags` that stable releases moved `latest` and prereleases moved `next`. To confirm `workspace:^` rewriting worked, inspect the `dependencies` field of any published `@openchoreo/*` package — every version specifier should be a concrete range (e.g. `^1.1.0`), never `workspace:^`.
 
+Confirm provenance was attached:
+
+```bash
+npm view @openchoreo/backstage-plugin --json | jq '.dist.attestations'
+```
+
+A non-null result means the OIDC path worked. `null` means the package was published without provenance — investigate before shipping the release.
+
+Finally, prove an unauthenticated consumer can install it. In a scratch directory with no `.npmrc` and no npm login:
+
+```bash
+yarn add @openchoreo/backstage-plugin@next
+```
+
 ### Re-running a tag
 
-The publish step is idempotent — `--tolerate-republish` makes `yarn npm publish` skip packages whose versions already exist on the registry and exit cleanly. Useful when a transient failure leaves some packages published and others not.
+The publish step is idempotent — `--tolerate-republish` makes `yarn npm publish` skip packages whose versions already exist on the registry and exit cleanly. Useful when a transient failure leaves some packages published and others not. Re-running still requires a fresh environment approval.
+
+### Registry history
+
+`@openchoreo/*` packages were published to GitHub Packages (`https://npm.pkg.github.com`) until the move to public npm. Versions `>= 1.1.0` were copied across by [`scripts/migrate-gh-packages-to-npmjs.js`](scripts/migrate-gh-packages-to-npmjs.js) and carry no provenance attestation (they predate trusted publishing). Versions older than `1.1.0` were not migrated and remain available only from GitHub Packages, which is now frozen and receives no new releases.
 
 ### One-time local dry run
 

README.md

@@ -220,19 +220,21 @@ For day-to-day development commands (test, lint, build, plugin development workf
 
 ## Installation
 
-The plugins are published to GitHub Packages. To install them in your Backstage application:
+The plugins are published to the public npm registry under the [`@openchoreo`](https://www.npmjs.com/org/openchoreo) scope. No registry configuration or authentication is required:
 
 ```bash
-# Configure npm to use GitHub Packages for @openchoreo scope
-echo "@openchoreo:registry=https://npm.pkg.github.com" >> .npmrc
-
-# Install the plugins you need
 yarn add @openchoreo/backstage-plugin
 yarn add @openchoreo/backstage-plugin-backend
 yarn add @openchoreo/backstage-plugin-api
 ```
 
-Note: You'll need a GitHub personal access token with `packages:read` permission to install from GitHub Packages.
+Releases are published from CI using [npm trusted publishing](https://docs.npmjs.com/trusted-publishers), so every version carries a signed [provenance attestation](https://docs.npmjs.com/generating-provenance-statements) linking the tarball to the workflow run that built it. Verify with:
+
+```bash
+npm audit signatures
+```
+
+Versions released before the move to npm (`1.2.x` and earlier) were migrated from GitHub Packages and have no attestation. Versions older than `1.1.0` remain available only from GitHub Packages.
 
 ### Wiring the plugins into your Backstage app
 

package.json

@@ -64,5 +64,5 @@
       "prettier --write"
     ]
   },
-  "packageManager": "yarn@4.4.1"
+  "packageManager": "yarn@4.18.0"
 }

packages/cell-diagram/package.json

@@ -16,8 +16,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.esm.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "backstage": {
     "role": "web-library"

packages/design-system/package.json

@@ -7,8 +7,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.esm.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",

packages/openapi-client-generator-node/package.json

@@ -8,8 +8,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",

packages/openchoreo-auth/package.json

@@ -8,8 +8,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",

packages/openchoreo-client-node/package.json

@@ -8,8 +8,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",

packages/portal-app/package.json

@@ -9,8 +9,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.esm.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",

packages/portal-backend/package.json

@@ -8,8 +8,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",

plugins/auth-backend-module-openchoreo-auth/package.json

@@ -8,8 +8,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",

plugins/catalog-backend-module-openchoreo-users/package.json

@@ -8,8 +8,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",

plugins/catalog-backend-module-openchoreo/package.json

@@ -13,8 +13,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "backstage": {
     "role": "backend-plugin-module",

plugins/openchoreo-backend/package.json

@@ -12,8 +12,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "backstage": {
     "role": "backend-plugin",

plugins/openchoreo-ci-backend/package.json

@@ -7,8 +7,7 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts",
-    "registry": "https://npm.pkg.github.com"
+    "types": "dist/index.d.ts"
   },
   "repository": {
     "type": "git",