Guides

Recipes for the workflows teams repeat every week.

Use these guides when you already understand the basics and need a concrete workflow for releases, previews, customer installs, CI, or policy debugging.

Start from scratch CLI reference

Release

Publish a production release

Build the package

build

cd packages/payments
npm ci
npm run build
npm test

Run a dry publish

dry run

packagepass publish . --tag next --dry-run

Publish and promote

publish

packagepass publish . --tag latest

packagepass dist-tag list @acme/payments

Audit the release

audit

packagepass audit events \
  --package @acme/payments \
  --type package.published \
  --limit 20

Previews

Ship a pull-request package

publish preview

packagepass preview publish ./packages/auth \
  --channel pr-482

npm install @acme/auth@preview-pr-482

When to use previews

Publish previews for customer SDK review apps, integration tests, generated-code diffs, or any workflow where consumers need a package before it becomes a stable release.

Customers

Give one customer access to one package

Create or identify the subject

subject

# In the CLI, subjects can be referenced directly.
# In the SDK/API, you can create customer records first.
customer:globex

Grant only install access

grant

packagepass grant add @acme/payments \
  --subject customer:globex \
  --action install

Mint a short-lived install token

token

packagepass token create install \
  --package @acme/payments \
  --subject customer:globex \
  --ttl 30d

Generate package manager config

npm

export PACKAGEPASS_TOKEN=<install-token>

packagepass setup @acme --manager npm --write

npm install @acme/payments

Configure npm, pnpm, Yarn, and Bun

.npmrc

@acme:registry=https://registry.preview.packagepass.dev/npm/
//registry.preview.packagepass.dev/npm/:_authToken=${PACKAGEPASS_TOKEN}

bunfig.toml

[install.scopes]
"@acme" = { url = "https://registry.preview.packagepass.dev/npm/", token = "$PACKAGEPASS_TOKEN" }

Do not commit tokens

Commit the registry mapping if your repo needs it, but keep PACKAGEPASS_TOKEN in the environment or secret manager.

Exchange a CI identity token

github actions

packagepass ci exchange \
  --provider github \
  --id-token "$ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
  --package @acme/payments

Use case

CI exchange lets your pipeline authenticate as a workflow identity instead of storing a long-lived publishing token.

Troubleshooting

Debug an install failure

Check local configuration

doctor

packagepass doctor @acme/payments

PACKAGEPASS_TOKEN=<install-token> \
  packagepass doctor @acme/payments

Verify the subject has install access

policy

packagepass policy explain @acme/payments \
  --subject customer:globex \
  --action install

Inspect audit events

audit

packagepass audit events \
  --package @acme/payments \
  --type policy.denied \
  --limit 50

Regenerate install config

setup

packagepass setup @acme --manager npm --write