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 before saving.

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

.gitlab.yml

image: node:latest
stages: 
  - deploy

deploy: 
  stage: deploy 
  script: 
    - 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.

Celebrate

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.

Comments

[Yohann Legrand]

Great post, thanks! I have one question, however: did you find a way to increment the package.json version automatically? I keep on forgetting, and it makes the pipeline fail (because npm publish an already existing tag)

[webbureaucrat]

Yes and no.

I see the benefit of that and did some research into it, but I haven't done it for any of my projects because to me, there's some value in the fact that it makes me manually set the build number because it keeps me from auto-incrementing a patch number on something that should be called a minor version upgrade or a major version upgrade. After a couple weeks, I've gotten in the habit of upgrading the build number.

Take a look at this GitLab CI script, though. It shows how to autoincrement and save an env variable.

[Yohann Legrand]

That's a good point. Thanks :)