Publishing an npm Package to GitHub Packages with GitHub Actions and GitHub App Authentication

In this post, we’ll walk through the process of publishing an npm package to GitHub Packages using GitHub Actions. We’ll also explore how to authenticate via a GitHub App, utilizing the peter-murray/workflow-application-token-action to obtain a JSON Web Token (JWT) for authentication. This approach provides a more secure and scalable method of managing access tokens in your CI/CD pipelines.

Prerequisites

Before we begin, ensure you have the following:

1. A GitHub repository for your npm package.
2. A GitHub App with the necessary permissions to generate a JWT.
3. An npm account (if you also want to publish to npm’s registry).

C

Step 1: Create a GitHub App

To authenticate your GitHub Actions via a GitHub App, you first need to create the GitHub App.

1. Navigate to GitHub Apps settings in your GitHub account.
2. Click on New GitHub App.
3. Fill in the required fields, such as the GitHub App name, Homepage URL, and Webhook URL (optional).
4. Under Repository Permissions, grant the app the following permissions:
   • Contents (read and write)
   • Packages (read and write)
   • Actions (read and write)
5. Save the App and generate a private key. That can be done in the end of the GitHub App settings page. Download this key, as you’ll need it later.

Step 2: Set Up Repository Secrets

Next, you’ll need to add the GitHub App’s credentials as secrets in your repository:

1. Go to your repository on GitHub.
2. Navigate to Settings > Secrets and variables > Actions.
3. Add the following secrets:
   • APP_ID: The ID of your GitHub App.
   • APP_PRIVATE_KEY: The private key you downloaded earlier (in base64 format).

Step 3: Configure GitHub Actions Workflow

Now that the GitHub App and repository secrets are set up, it’s time to configure the GitHub Actions workflow. This workflow will build your npm package and publish it to GitHub Packages.

Create a .github/workflows/publish.yml file in your repository with the following content:

name: Publish Package

on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: 16
        registry-url: https://npm.pkg.github.com/ORG_OR_USERNAME

    - name: Authenticate using GitHub App
      id: jwt
      uses: peter-murray/workflow-application-token-action@v3
      with:
        application_id: $
        application_private_key: $

    - name: Publish to GitHub Packages
      run: npm publish
      env:
        NODE_AUTH_TOKEN: $

    - name: Publish to npm registry
      run: npm publish --registry=https://registry.npmjs.org
      env:
        NODE_AUTH_TOKEN: $

Step 4: Install GitHub App So it can be used in the workflow

Step 4: Understanding the Workflow

Let’s break down what’s happening in the workflow file:

1. Checkout code: The actions/checkout action checks out the repository code.

2. Set up Node.js: The actions/setup-node action sets up the Node.js environment. We specify the Node.js version and the registry URL for GitHub Packages.

3. Authenticate using GitHub App: The peter-murray/workflow-application-token-action is used to generate a JWT using the GitHub App’s credentials. This JWT is used to authenticate with GitHub Packages.

4. Publish to GitHub Packages: The npm publish command is used to publish the package to GitHub Packages. The NODE_AUTH_TOKEN environment variable is set to the JWT obtained in the previous step.

5. Publish to npm registry: Optionally, if you want to publish your package to npm’s registry as well, you can do so in this step. Ensure that you have added the NPM_TOKEN secret to your repository.

Step 5: Test the Workflow

After pushing your changes to the main branch, the workflow will trigger automatically. You can check the progress and logs in the Actions tab of your repository.

If everything is set up correctly, your npm package will be published to GitHub Packages (and npm if configured).

Conclusion

By using a GitHub App for authentication and leveraging GitHub Actions, you can securely and efficiently automate the process of publishing npm packages to GitHub Packages. The peter-murray/workflow-application-token-action simplifies the JWT generation process, allowing you to manage authentication in a secure and scalable manner.

This setup provides a robust CI/CD pipeline, enabling you to focus on development while ensuring your packages are published seamlessly.