Github Packages NPM

GitHub Packages (npm) AI Skill Guide

Overview & Engine Architecture

GitHub Packages hosts npm packages under https://npm.pkg.github.com tied to a GitHub user or organization. Publish with publishConfig and a scoped name (@org/pkg); authenticate with GITHUB_TOKEN in Actions or a PAT with read:packages/write:packages locally. Agents configure .npmrc correctly, avoid leaking tokens, and align package permissions with repo visibility.

package.json (name @org/pkg)
   -> npm publish
       -> npm.pkg.github.com
Consumers -> .npmrc (@org:registry=...) + token

When to use this skill

• Publishing private or internal npm libraries to GitHub Packages
• Consuming @org/* packages in apps and Actions
• Migrating from npmjs private registries
• Debugging 401/403 publish or install failures

Operational directives

1. Scope packages to the org (@myorg/utils); set "registry": "https://npm.pkg.github.com" in publishConfig.
2. Never commit tokens; use NODE_AUTH_TOKEN / GITHUB_TOKEN env substitution in .npmrc.
3. Grant least package permissions; GITHUB_TOKEN write is limited to the current repo unless workflows are configured otherwise.
4. Version with semver; prefer CI publish on tagged releases.
5. Document install steps for external contributors who need PATs.

publishConfig sketch

{
  "name": "@acme/sdk",
  "version": "1.4.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

.npmrc sketches

# project or user level - token via env
@acme:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

# GitHub Actions
- uses: actions/setup-node@v4
  with:
    registry-url: https://npm.pkg.github.com
    scope: "@acme"
- run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Common failures

Best practices

• Publish from CI on v* tags; keep local publish rare.
• Pair with provenance/signing policies your org requires.
• For public OSS, prefer npmjs.com; use GitHub Packages for private/internal.
• Delete/deprecate old packages carefully - consumers may pin exact versions.

Limitations

• Cross-repo GITHUB_TOKEN publish permissions depend on Actions settings and org policy.
• Fine-grained PATs and classic PATs differ in package scopes - verify current GitHub docs.
• Yarn/pnpm registry config keys differ slightly from npm.

Related skills

• @dependabot-config - update consumers of private packages carefully
• @gpg-signing - signed release tags before publish
• @github-actions - release workflow wiring