Welcome! We notice you're using an outdated browser, which will result in a degraded experience on this site. Please consider a modern, fully supported browser.


from legacy to functional and very little in between.

Continuously Deploying an NPM Package with GitLab CI/CD

Setting up continuous deployment is important to me, even when publishing is as simple as it is on npm. The official GitLab documentation, though, is a little more than I need and geared toward their own npm repository, so I'd like to gather the information I need here in a brief article.

Generate and store an authentication token

The npm team has made this straightforward.

Generating the token in npm

  1. Go to npmjs.com and log in if you haven't already.
  2. Click on your profile picture at the top right.
  3. Select the fifth item, "Access Tokens."
  4. Click "Generate New Token" on the top right of the page.
  5. Select the middle option, "automation" for the right security settings.
  6. Click "Generate Token."
  7. Copy the token to your clipboard.

Storing the token in GitLab

  1. Log into GitLab and open the project you intend to automate.
  2. Select "Settings" at the bottom of the menu on the left. This will open a submenu.
  3. Select "CI/CD."
  4. Find the "Variables" section of the CI/CD menu and click "expand" on the right.
  5. Click the green "Add variable" button at the bottom.
  6. Fill in the "Key" text box with "NPM_TOKEN".
  7. Fill in the "Value" box with the token you copied from earlier.
  8. Make sure the "Type" is set to "variable" instead of "file."
  9. Important: Make sure both checkboxes are checked to protect and mask the variable.

Protecting the variable keeps it from being shared by less-trusted contributors, and masking it keeps the variable from being displayed in the console output when the pipeline runs. The npm authentication token stored in this variable is very sensitive--if an attacker got ahold of it, they could use it to push malicious code to your package repo, so it's important to keep it as secure as possible.

Set up the pipeline with your .gitlab.yml

This is the easy part. Copy the following text and save it to a file called .gitlab.yml


image: node:latest
- deploy

stage: deploy
- echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
- npm publish

Just to break it down: This file grabs an image that has node installed. It deploys by creating a file called .npmrc that defines where our registry is and what our authentication token is based on the environment variable NPM_TOKEN we created earlier. With that file in place, npm publish will run.


Update your package.json with a fresh version number to make sure the push succeeds, then commit and push the new .gitlab.yml and the edited package.json. The pipeline will succeed every time you increment the version number.

I write to learn, so I welcome your constructive criticism. Report issues on GitLab.

← Home