Skip to content
[ PIER ]

Use the registry in CI

CI uses the same .npmrc (or .yarnrc.yml) as a developer workstation — the only difference is the token comes from a secret store instead of a file on disk.

Step 1: store the token as a secret

Section titled “Step 1: store the token as a secret”
  1. Mint a CI-specific token in Packages → Manage tokens named ci-github (or similar). Use a separate token per pipeline so you can revoke it independently.
  2. Add it as a secret:
    • GitHub Actions → repo Settings → Secrets and variables → Actions → PIER_NPM_TOKEN.
    • GitLab CI → project Settings → CI/CD → Variables → PIER_NPM_TOKEN (protected, masked).

Step 2: write the .npmrc in the job

Section titled “Step 2: write the .npmrc in the job”

GitHub Actions — npm / pnpm / bun

Section titled “GitHub Actions — npm / pnpm / bun”
name: build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - name: Configure Pier registry
        run: |
          cat > .npmrc <<EOF
          registry=https://YOUR-PIER-HOST/registry/npm/
          //YOUR-PIER-HOST/registry/npm/:_authToken=${PIER_NPM_TOKEN}
          always-auth=true
          EOF
        env:
          PIER_NPM_TOKEN: ${{ secrets.PIER_NPM_TOKEN }}
      - run: npm ci
      - run: npm run build

For pnpm replace npm ci with pnpm install --frozen-lockfile, for bun with bun install --frozen-lockfile.

GitHub Actions — yarn 4 (berry)

Section titled “GitHub Actions — yarn 4 (berry)”
      - name: Configure Pier registry (yarn berry)
        run: |
          cat > .yarnrc.yml <<EOF
          npmRegistryServer: "https://YOUR-PIER-HOST/registry/npm/"
          npmAuthToken: "${PIER_NPM_TOKEN}"
          npmAlwaysAuth: true
          nodeLinker: node-modules
          EOF
        env:
          PIER_NPM_TOKEN: ${{ secrets.PIER_NPM_TOKEN }}
      - run: corepack enable && yarn install --immutable

GitLab CI

Section titled “GitLab CI”
build:
  image: node:24
  before_script:
    - |
      cat > .npmrc <<EOF
      registry=https://YOUR-PIER-HOST/registry/npm/
      //YOUR-PIER-HOST/registry/npm/:_authToken=${PIER_NPM_TOKEN}
      always-auth=true
      EOF
  script:
    - npm ci
    - npm run build

Step 3: publish from CI (optional)

Section titled “Step 3: publish from CI (optional)”
      - name: Publish
        if: startsWith(github.ref, 'refs/tags/v')
        run: npm publish
        env:
          NPM_CONFIG_REGISTRY: https://YOUR-PIER-HOST/registry/npm/

The .npmrc written in step 2 carries the bearer; npm publish picks it up automatically.

Tips

Section titled “Tips”
  • One token per pipeline. Revoke without touching anything else.
  • always-auth=true is mandatory for yarn 1; harmless for npm/pnpm/bun. Yarn 4 wants npmAlwaysAuth: true in .yarnrc.yml.
  • Cache node_modules between runs. The proxy is fast, but skipping the install entirely is faster — use the standard actions/setup-node cache.
  • Verify the registry is reachable before installing — a one-line curl -sf https://your-pier-host/registry/npm/-/ping saves a confusing 5-minute install error if Traefik or DNS is misbehaving.
Section titled “Related”