Docs › Private install (Artifact Registry npm)

Installing `@fabricstack/*` packages from the private registry

Fabric's npm packages are private. They publish only to the GCP Artifact Registry npm repository fabric-npm in project boot-464019 (region us-central1), never to the public npm registry (decision D19; docs/specs/platform-gaps/15-private-isolation-rename.md §4). To install them you need two things:

1. **Scope routing** — the committed root .npmrc already maps the @fabricstack scope to the registry. You do not add anything to it. 2. **A short-lived credential** — an OAuth access token for your Google identity (or, in CI, for the deployer service account), written into *your user-level* ~/.npmrc by the google-artifactregistry-auth helper.

Registry URL: https://us-central1-npm.pkg.dev/boot-464019/fabric-npm/

The two `.npmrc` files (read this first)

Credentials go to the **user** npmrc only. The repository .npmrc must never gain an _authToken, _password or token= line; CI (.github/workflows/ar-smoke.yml) and the public-push guard both check it. If you ever see a credential in the repo file, remove it and rotate the token.

Developer setup

Prerequisites: gcloud CLI installed, Node.js 22 with npm 10, and roles/artifactregistry.reader on fabric-npm for your Google account (ask a maintainer; the binding is per repository, not per project).

1. Sign in to Google Cloud

gcloud auth login

This signs in the gcloud CLI itself. The helper below can use that sign-in directly. If you prefer Application Default Credentials (the same mechanism client libraries use), run this instead or in addition:

gcloud auth application-default login

Either sign-in works; ADC is the one to use on a machine where several tools share Google credentials.

2. Refresh the registry credential into your user npmrc

From the repository root (the --repo-config file is the committed .npmrc, which tells the helper which pkg.dev registries you use):

npx google-artifactregistry-auth --repo-config=.npmrc --credential-config=~/.npmrc

What this does: reads the registries from .npmrc, obtains an access token for your Google identity (from gcloud auth login, ADC, or GOOGLE_APPLICATION_CREDENTIALS), and writes //us-central1-npm.pkg.dev/boot-464019/fabric-npm/:_authToken=... into ~/.npmrc. It does not modify the repository .npmrc.

On Windows PowerShell, ~ is not expanded inside an argument; spell the path out:

npx google-artifactregistry-auth --repo-config=.npmrc --credential-config="$HOME/.npmrc"

3. Install

npm install @fabricstack/smoke
node -e "console.log(require('@fabricstack/smoke'))"
# { ok: true }

@fabricstack/smoke is the throwaway rehearsal package published by the smoke workflow; any @fabricstack/* package installs the same way. Outside the repository, put the single scope-routing line in the consuming project's .npmrc (or pass --registry https://us-central1-npm.pkg.dev/boot-464019/fabric-npm/ for a one-off) and run step 2 with --repo-config pointing at that file.

Confirm what you are talking to:

npm ping --registry https://us-central1-npm.pkg.dev/boot-464019/fabric-npm/
npm view @fabricstack/smoke --registry https://us-central1-npm.pkg.dev/boot-464019/fabric-npm/

CI setup (GitHub Actions)

CI never holds a long-lived registry credential. A job authenticates to GCP through Workload Identity Federation with the existing organization variables, then runs the same helper. The reference implementation is .github/workflows/ar-smoke.yml; the essential steps:

permissions:
  contents: read
  id-token: write

steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v6
    with:
      node-version: 22
  - name: Authenticate to GCP (Workload Identity Federation)
    uses: google-github-actions/auth@v2
    with:
      workload_identity_provider: ${{ vars.GCP_WORKLOAD_IDENTITY_PROVIDER }}
      service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
  - name: Refresh Artifact Registry npm credentials
    run: npx -y google-artifactregistry-auth --repo-config=.npmrc --credential-config="$HOME/.npmrc"
  - run: npm ping --registry https://us-central1-npm.pkg.dev/boot-464019/fabric-npm/

Notes:

• id-token: write is what lets the runner mint the OIDC token that WIF exchanges; without it google-github-actions/auth fails before touching GCP.
• Do not set registry-url on actions/setup-node: it writes its own .npmrc with a NODE_AUTH_TOKEN placeholder that conflicts with the helper.
• The service account (vars.GCP_SERVICE_ACCOUNT, github-deployer@boot-464019.iam.gserviceaccount.com) holds roles/artifactregistry.writer on fabric-npm only, so it can publish as well as install. A job that only installs still uses the same steps.
• google-artifactregistry-auth finds the WIF credential through GOOGLE_APPLICATION_CREDENTIALS, which google-github-actions/auth@v2 exports by default.

Publishing (maintainers and the release train)

Every @fabricstack/* package sets publishConfig.registry to the registry URL, and npm publish honors that over any ambient config. Publication is CI's job alone: the private release train (.github/workflows/publish-npm-private.yml, WP-RN-07) publishes all 43 packages in dependency waves under a candidate dist-tag, validates the exact version from this registry, and only then moves the channel (main → latest, staging → staging, develop → develop) and creates the immutable fabric/<branch>/v<version> tag. Recovery from a tag, dist-tag repair and the dry-run commands are in docs/RELEASE-RUNBOOK.md; the model is in docs/release-pipeline.md. Publishing anything under @fabricstack to the public npm registry is forbidden and guarded (spec 15 §4.3 G1–G6).

Troubleshooting

Provisioning record (what exists in GCP, IAM policy, rollback): docs/specs/platform-gaps/phase0/ar-provisioning.md.