Using Github Packages as npm registry

by michael
7 minutes
Using Github Packages as npm registry

Introduction

Github Packages is Github's npm registry (or rather, their package registry) offering. It supports various types of packages and images, but this article will focus on using it as an npm repo where we will automatically post a new package version on release time.

We use yarn for our package management, so instead of a package-lock.json we have a yarn.lock file. To make the build environment in Github Actions run the yarn install correctly, make sure to add the --frozen-lockfile argument.

Github Actions are stored in the.github/workflows/ folder has YAML files. Depending on what is configured in the on: section, they are executed automatically on that event. The following is an example (based on the Node.js Package example from Github) that will publish a yarn based nodejs package on release.

Notice the ${{secrets.GITHUB_TOKEN}} parameter. This is an auto-generated token that is being generated when the Action is started, and deleted afterwards. This is not the token you use to authenticate yourself for actually using the npm package later on.

Publish Action

The following workflow is a Github Action to build, test and publish a prepared repository to the Github Package repository. This is a single job Action, which means:

  • Pro: significantly faster than multiple job Action (every step is only run once, in order)
  • Con: needs to make sure that tests are properly cleaned up so that no leftovers end up in package

.github/workflows/npm-publish.yml

name: Node.js Package

on:
  release:
    types: [created]

jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://npm.pkg.github.com
      - run: yarn install --frozen-lockfile
      - run: yarn build
      - run: yarn test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

The workflow can also be run in multiple jobs, making it easier to differentiate the results (e.g. to publish different versions or to different registries) and to run tests seperate from publish builds - at the cost of time:

  • Pro: clear separation
  • Pro: can use results of one job for multiple other jobs
  • Con: slower, as multiple steps need to run again for each job (costing time and money)

.github/workflows/npm-publish.yml

name: Node.js Package
on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      - run: yarn install --frozen-lockfile
      - run: yarn build
      - run: yarn test

  publish-gpr:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://npm.pkg.github.com
      - run: yarn install --frozen-lockfile
      - run: yarn build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

Read published packages

To use the published package in a repo they can be referred to as normal in the package.json:

  "dependencies": {
    "@mycompany/de.mycompany.corporate.ci-cd-playground": ">=1.0.0"
  }

or via npm i "@mycompany/de.mycompany.corporate.ci-cd-playground" or yarn add "@mycompany/de.mycompany.corporate.ci-cd-playground"

So that npm/yarn actually are able to find the @mycompany repo, .npmrc and .yarnrc files are used at the root of the project.

.npmrc

@mycompany:registry=https://npm.pkg.github.com

.yarnrc

"@mycompany:registry" "https://npm.pkg.github.com/mycompany"

Authentication

The publish action does not require any specific authentication to be set up, the NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} token gets generated automatically within the context of the Action, and then is discarded afterwards.

To actually use the package, you need to both tell npm/yarn where to find it as well as authenticate against the repo, if it is a private repository.

npm

To use the package in another project requires authentication to be set up. You will have to set up a Personal Access Token on Github for this. Image description

The read/write one you only need if you also plan to npm publish manually, otherwise read access is enough.

To create the authentication files for your profile, one way is to use npm login:

> npm login --registry=https://npm.pkg.github.com
Username: mycompany-login
Password: GITHUB_TOKEN (not the users password)
Email: (this IS public) somemail@mycompany.de
Logged in as mycompany-login on https://npm.pkg.github.com/.

That generates a .npmrc file in your profile folder (with your access token) which npm uses for authentication.

//npm.pkg.github.com/:_authToken=xxxxxxxxx

where xxxx is the token.

yarn

yarn login --registry=https://npm.pkg.github.com yarn login v1.22.5 question npm username: mycompany-login question npm email: somemail@mycompany.de

That generates a .yarnrc file in your profile folder for authentication:

# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
# yarn lockfile v1

email somemail@mycompany.de
username  mycompany-login
"_authToken" xxxxxxxxxxxxxxx
"@mycompany:registry" "https://npm.pkg.github.com/mycompany"

This should be all.

Currently there are no comments, so be the first!