Publishing Private npm Packages Using GitHub Packages

There are already many articles covering this topic, but since I ran into several issues when I actually tried it, I'm documenting it here as a memo.

What I want to do

Use an npm package published privately to GitHub Packages across multiple applications.

Be able to install my own package from GitHub Packages by specifying a version, just like public packages retrieved from registries like npm.

What is GitHub Packages

https://github.com/features/packages

GitHub Packages is a registry provided by GitHub.
You can publish packages restricted to a specific GitHub user or organization.

Publishing a Package to GitHub Packages

package.json Settings

Configure the following information in the package.json of the package you want to publish.

• name: Package name
  • Format: @<scope>/<package-name>
  • Example: @052hide/my-lib
• version: Package version
  • Format: x.x.x
  • Example: 1.0.0
• publishConfig: Registry URL
  • Format: { "@<scope>:registry": "<GitHub Packages registry URL>" }
  • Example: { "@052hide:registry": "https://npm.pkg.github.com" }
• private: Remove this
  • You need to remove private: true to publish the package.
    Removing this doesn't mean the package published to GitHub Packages will become public.

{
+  "name": "@052hide/my-lib",
+  "version": "1.0.0",
+  "publishConfig": {
+    "@052hide:registry": "https://npm.pkg.github.com"
+  },
-  "private": true
  ...
}

.npmrc Settings

Configure the following information in the .npmrc of the package you want to publish.

• _authToken: Personal Access Token for publishing to GitHub Packages
  • Assuming this will be specified from GitHub Actions, it will be received via an environment variable named GITHUB_PACKAGES_NPM_PUBLISH_AUTH_TOKEN.

+ //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_NPM_PUBLISH_AUTH_TOKEN}

Publishing from local

I won't be publishing from local, so this part is omitted^[1]

Publishing from GitHub Actions

name: Publish Package
on:
  release:
    types: [published]
jobs:
  build:
    # Omitted

  publish:
    needs: build
    name: Publish GitHub Packages
    runs-on: ${{ matrix.os }}
    timeout-minutes: 30

    strategy:
      matrix:
        os: [ubuntu-latest]

    permissions:
      packages: write # Requires write permission for GitHub Packages
      contents: read # Requires read permission for repository content

    steps:
      - name: Checkout 🛎
        uses: actions/checkout@v4.1.0

      - uses: actions/setup-node@v3
        with:
          node-version: 18

      - run: npm publish
        env:
          GITHUB_PACKAGES_NPM_PUBLISH_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} # Specify GITHUB_TOKEN with permissions defined in the permissions block

Successfully published to GitHub Packages 🎉

Using the Published Package

GitHub Package Settings

Registering repositories

Add repositories that are permitted to install the package.

https://github.com/orgs/<org>/packages/npm/<package-name>/settings or https://github.com/users/<user>/packages/npm/<package-name>/settings

Installing from GitHub Packages

.npmrc Settings

Configure the following information in .npmrc.

• registry: Registry URL for the scope
  • Format: @<scope>/<package-name>=https://npm.pkg.github.com
  • Example: @052hide/my-lib=https://npm.pkg.github.com
• _authToken: Personal Access Token for retrieving from GitHub Packages
  • Assuming this will be specified from GitHub Actions, it will be received via an environment variable named GITHUB_PACKAGES_NPM_READ_AUTH_TOKEN.

+ @052hide:registry=https://npm.pkg.github.com
+ //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_NPM_READ_AUTH_TOKEN}

Installing the Package Locally

Generating a PAT

https://github.com/settings/tokens

• Permissions
  • read:packages

Setting GITHUB_PACKAGES_NPM_READ_AUTH_TOKEN

export GITHUB_PACKAGES_NPM_READ_AUTH_TOKEN=<PAT>
# export GITHUB_PACKAGES_NPM_READ_AUTH_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Installing the package

npm install <package-name>
# npm install @052hide/my-lib

Installing the Package in GitHub Actions

package.json

{
  "dependencies": {
    "@052hide/my-lib": "1.0.0"
  }
}

workflow.yml

name: Install Packages

on:
  push:

jobs:
  ci:
    name: CI
    runs-on: ${{ matrix.os }}
    timeout-minutes: 30

    strategy:
      matrix:
        os: [ubuntu-latest]

    steps:
      - name: Checkout 🛎
        uses: actions/checkout@v4.1.0

      - name: 'Install Node Modules'
        run: npm install
        env:
          GITHUB_PACKAGES_NPM_READ_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Specify GITHUB_TOKEN
          # If using a Composite Action, specify github.token

You are now ready to use npm packages published to GitHub Packages from both your local environment and GitHub Actions! 🎉🎉🎉

脚注

1. Requires specifying a PAT with appropriate permissions in GITHUB_PACKAGES_NPM_PUBLISH_AUTH_TOKEN