II.
Page overview
Reference · livepage:docs-user-guide-private-install
Installing `@fabricstack/*` packages from the private registry overview
Inspect the raw attributes, linked wiki pages, and inbound or outbound graph edges for page:docs-user-guide-private-install.
Attributes
nodeKind
Page
sourcePath
docs/user-guide/private-install.md
sourceKind
repo-docs
title
Installing `@fabricstack/*` packages from the private registry
displayName
Installing `@fabricstack/*` packages from the private registry
slug
docs/user-guide/private-install
articlePath
wiki/docs/user-guide/private-install.md
article
[Docs](./index.md) › 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)
| File | Committed? | Contains | Who writes it |
|---|---|---|---|
| `<repo>/.npmrc` | yes | `@fabricstack:registry=https://us-central1-npm.pkg.dev/boot-464019/fabric-npm/` (plus workspace settings) | maintainers, by pull request |
| `~/.npmrc` (your home directory) | never | `//us-central1-npm.pkg.dev/boot-464019/fabric-npm/:_authToken=<token>` | `google-artifactregistry-auth`, on every refresh |
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
```bash
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:
```bash
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):
```bash
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:
```powershell
npx google-artifactregistry-auth --repo-config=.npmrc --credential-config="$HOME/.npmrc"
```
### 3. Install
```bash
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:
```bash
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:
```yaml
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](../RELEASE-RUNBOOK.md); the model is in [docs/release-pipeline.md](../release-pipeline.md). Publishing anything under `@fabricstack` to the public npm registry is forbidden and guarded (spec 15 §4.3 G1–G6).
## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| `npm ERR! 403 Forbidden` on install or `npm view` | your Google account has no `roles/artifactregistry.reader` on `fabric-npm` | ask a maintainer to run `gcloud artifacts repositories add-iam-policy-binding fabric-npm --location=us-central1 --project=boot-464019 --member=user:<you> --role=roles/artifactregistry.reader` |
| `npm ERR! 403 Forbidden` on `npm publish` | the identity has reader but not writer | publishing is CI's job; if you really need to, ask for `roles/artifactregistry.writer` on the repository |
| `npm ERR! 401 Unauthorized` after it worked earlier | the access token expired (they live about one hour) | rerun step 2 (`npx google-artifactregistry-auth ...`) |
| `npm ERR! 401` immediately, `~/.npmrc` has no `pkg.dev` line | the helper wrote to a different file, or `--credential-config` pointed at the repo file | rerun step 2 with an explicit absolute path for `--credential-config`; check `npm config get userconfig` |
| `Could not load the default credentials` from the helper | no `gcloud auth login` / ADC on this machine | run step 1 |
| `E404 Not Found` for `@fabricstack/<name>` | the scope is not routed (consuming project has no `.npmrc` line), so npm asked the public registry | add `@fabricstack:registry=https://us-central1-npm.pkg.dev/boot-464019/fabric-npm/` to that project's `.npmrc` |
| CI: `google-github-actions/auth` fails with a permission error | the workflow lacks `id-token: write`, or the repository is not in the service account's `roles/iam.workloadIdentityUser` binding (`attribute.repository/a5c-ai/<repo>`) | add the permission; ask an owner to review the binding (`gcloud iam service-accounts get-iam-policy github-deployer@boot-464019.iam.gserviceaccount.com`) |
| a credential line appears in `<repo>/.npmrc` | someone ran the helper with `--credential-config=.npmrc` | delete the line, do not commit, rotate nothing (tokens expire) but recheck `git status` before every commit |
Provisioning record (what exists in GCP, IAM policy, rollback): `docs/specs/platform-gaps/phase0/ar-provisioning.md`.
documents
[]
Outgoing edges
None.
Incoming edges
contains_page1
- page:docs-user-guide·PageBabysitter User Guide