19. 09. 2024
Development, DevOps
12. 09. 2024
Mattia Codato
Development, DevOps
Publish NPM Package to GitHub Packages Registry with GitHub Actions
With the rise of continuous integration and delivery (CI/CD) in modern software development, automating tasks like publishing npm packages has become crucial for efficiency. GitHub packages Registry (npm.pkg.github.com) allows developers to host and manage npm packages directly within GitHub, offering a seamless experience for both private and public repositories.
By leveraging GitHub Actions, developers can automate the process of publishing npm packages to GitHub Packages Registry without needing any manual intervention. This eliminates repetitive tasks, reduces the likelihood of human error, and ensures a consistent release process. Using GitHub Actions, you can automatically publish your package whenever you push new code to specific branches or tags, all while securely handling authentication via GitHub’s built-in GITHUB_TOKEN.
In this guide, we’ll walk through how to configure GitHub Actions to publish npm packages directly to the GitHub Packages Registry, ensuring a smooth and automated workflow for your package releases.
Step 1: Set up the .npmrc file for authentication
When publishing packages to npm.pkg.github.com, you must authenticate with a GitHub token to give GitHub Actions permission to publish the package. This is done via the .npmrc configuration file.
Create .npmrc in the root directory
In the root of your project directory (the same one as your package.json file), create a file named .npmrc with the following content (don’t forget to replace the variables with your actual values):
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@your-github-username:registry=https://npm.pkg.github.com/
always-auth=trueHere’s what each part means:
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}: This tells npm to use an environment variable calledNODE_AUTH_TOKENfor authentication when interacting with the GitHub Packages Registry@your-github-username:registry=https://npm.pkg.github.com/: This line directs npm to use the GitHub Packages Registry for any packages scoped with@your-github-usernamealways-auth=true: Forces npm to authenticate for every request to the registry, ensuring secure and consistent access to the package registry, especially for private repositories
Make sure to replace @your-github-username with your actual GitHub username (or organization name if the package is hosted under an organization).
Why use NODE_AUTH_TOKEN?
Instead of hard-coding the GitHub token in the .npmrc file, you use ${NODE_AUTH_TOKEN}. This token will be injected securely via GitHub Actions, avoiding the risk of exposing sensitive credentials in your repository.
Step 2: Modify package.json
To make sure npm knows to publish to the GitHub Packages Registry, add or modify the following in your package.json:
{
"name": "@your-github-username/your-package-name",
"repository": {
"type": "git",
"url": "https://github.com/your-github-username/your-repo.git"
},
"publishConfig": {
"registry": "https://npm.pkg.github.com/"
}
}This ensures that npm publishes your package to the GitHub packages Registry every time the workflow runs.
Step 3: Configure GitHub actions workflow
With .npmrc and package.json files correctly set up, you can now create the GitHub Actions workflow to automate the publishing process.
Here’s an example of what your workflow file might look like, incorporating the .npmrc configuration:
Create .github/workflows/npm-publish.yml
name: Publish NPM Package
on:
push:
branches:
- main # Change this to the branch you want to publish from
jobs:
publish:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 'lts/*' # Adjust for the version your project needs
registry-url: 'https://npm.pkg.github.com/'
- name: Install dependencies
run: npm install
- name: Build package
run: npm run build
- name: Publish to GitHub Packages Registry
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Explanation:
- Set up Node.js: This action sets up Node.js and configures the registry to use
npm.pkg.github.com. - Install dependencies: Installs all dependencies before building the package.
- Build package: This step is optional if your package requires a build step. Replace it with your actual build script.
- Publish: Publishes the npm package to GitHub Package Registry, using the
NODE_AUTH_TOKENfor authentication.NODE_AUTH_TOKENis automatically populated with theGITHUB_TOKENsecret, which is generated as an access token for the repository each time the workflow job starts.
Conclusion
Once the workflow has been successfully executed, the npm package will be available in the Packages section of the same GitHub repository. From there, you can manage, view, and share your published package, streamlining the distribution process for your project.
These Solutions are Engineered by Humans
Did you find this article interesting? Are you an “under the hood” kind of person? We’re really big on automation and we’re always looking for people in a similar vein to fill roles like this one as well as other roles here at Würth Phoenix.
Mattia Codato
Software Developer - IT System & Service Management Solutions at Würth Phoenix
Author
