Skip to content

ADR-0002: Migrate from Verdaccio to GitHub Packages for npm

Date: 2026-05-21
Status: Accepted
Decision makers: Dev team

Context

We maintained a self-hosted Verdaccio instance as a private npm registry for internal JavaScript/Node packages. While Verdaccio worked, it introduced operational overhead: the instance needed to be hosted, secured, kept available, and backed up. Credentials and registry configuration had to be managed separately from our existing GitHub infrastructure.

All of our source code already lives in GitHub under the subscribed-aps organisation. GitHub Packages provides a hosted npm registry that is directly tied to the same organisation, authentication model, and access controls we already use.

We considered:

  • Verdaccio (status quo) — self-hosted, flexible, but requires infrastructure maintenance and separate auth management
  • npm private registry (npmjs.com) — hosted, but a paid add-on that duplicates capabilities already included in our GitHub plan
  • GitHub Packages — native to our GitHub organisation, uses PAT-based auth, no separate infrastructure, included in our plan

Decision

We migrate the npm package registry from Verdaccio to GitHub Packages (https://npm.pkg.github.com) under the @subscribed-aps scope.

Verdaccio is decommissioned. All packages are republished to GitHub Packages. Any project or developer installing internal npm packages must authenticate with a GitHub personal access token (classic).

Consequences

Positive:

  • No registry infrastructure to maintain — GitHub Packages is fully managed
  • Auth consolidates into GitHub PATs — the same mechanism already used for Satis and GitHub Actions
  • Package visibility inherits organisation access controls automatically
  • Package versions are linked to GitHub releases, improving traceability

Negative / trade-offs:

  • Every developer and CI runner needs a read:packages GitHub PAT configured locally
  • package.json must include explicit publishConfig and repository fields — publishing is not zero-config
  • GitHub Packages does not proxy the public npm registry — it only serves packages explicitly published under the scoped namespace

See the GitHub Packages guide for setup and usage instructions.