Setup a private NPM package in Gitlab

27 Jul 2023 · 4 min read

Link copied successfully
Setup a private NPM package in Gitlab illustration

In this article, I'll guide you through setting up a private package in GitLab—a crucial step for secure code management and collaboration. Learn how to enable the package registry, securely publish and manage private packages, and ensure controlled distribution of your organization's proprietary code components.

(Optional) Creates the project

If you don't have any package to be published yet, let's create a new one first.

# init a nodejs project
npm init -y

creates simple add function for now in app.js. We just create a simple function using common js, so later we can import or require it.

// app.js

function addition(a, b) {
  return a + b;
}

module.exports = addition

Edit the .package.json

{
  "name": "@my-org/simpleadd",
  "version": "1.0.0",
  "description": "A simple addd function",
  "main": "app.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "Your name",
  "license": "ISC"
}

Now we good to go. Our expected final result later is to be able to use this module in a node project by importing or requiring it.

import addition from "@my-org/simpleadd";

// or

const addition = require("@-org-name/simpleadd");

console.log(addition(9,7)) // -> 16

Understanding Instance, Group and Project in Gitlab

When developing and publishing package in GitLab, terms Instance, Group and Project are important to be understand. Because some convention will divided by these terms as category.

  • Projects represent individual repositories containing source code, documentation, and other assets related to a specific software project.
  • Groups in GitLab are organizational structures that allow users to categorize and manage multiple related projects. By grouping projects together, teams can efficiently collaborate on larger initiatives and manage permissions and access controls collectively.
  • Instance refers to the entire GitLab ecosystem, representing an individual installation of GitLab on a server. As an open-source Git package manager, GitLab provides the flexibility of being installed and hosted on various servers. In this context, the term "instance" is the specific installation of GitLab, along with all the repositories and groups managed within it. An example of a GitLab instance is the one hosted by Microsoft at https://gitlab.com.

gitlab instances

Above figure depicted the possible structure of a gitlab instance. An instance can have many groups or projects. A group can have subgroups and projects. A project is standalone entity.

Creating Instance level NPM package

We want the package to be able to be installed accross all projects in the GitLab instance. Thus we need to adhere the Naming convention by adding scope prefix for our package name.

The prefix is our Group name. Suppose our package project URL is "https://gitlab.com/my-org/engineering-group/analytics", then the scope is @my-org. So, our package name would be @my-org/package-name. Make sure the name of of the package inside package.json is "name": "@my-org/package-name".

Publishing the package

There are two approaches we can take to publish the package, via command line or GitLab pipeline.

Publishing via Command line

creates file named .npmrc in your project root contains below snippet

@my-org:registry=https://gitlab.com/api/v4/projects/your_project_id/packages/npm/
//gitlab.com/api/v4/projects/your_project_id/packages/npm/:_authToken="NPM_TOKEN"

Then add below snippet to package.json

"publishConfig": {
    "@my-org:registry": "https://gitlab.com/api/v4/projects/your_project_id/packages/npm/"
  }

After all set and your package code already pushed to the remote repository, run below command in your terminal

npm publish

Now your package is already published and can be found in Deploy > package registry

Notes

  • Get your project id at project overview of your project project id
  • NPM_TOKEN here can be get by go to Settings > Repository > Deploy tokens, then creates a new token with read_package_registry and write_package_registry scopes.

deploy tokens

Publishing via CI/CD pipeline

This approach are simpler and no need any deploy token. You can delete the .npmrc file if publishing via pipeline. In exchange, creates a .gitlab-ci.yml file contains below snippet

image: node:latest

stages:
  - deploy

deploy:
  stage: deploy
  script:
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc
    - npm publish

Now, everytime you push new updates to the remote repository, the pipeline will run in Build > pipelines and publish the updates automatically. Don't forget to change the package version inside package.json, or your publish will failed if same version already exist.

Installing the package in a project

Ok, time to install our published package inside our nodejs project. Create .npmrc file, and add below codes

@my-org:registry=https://gitlab.com/api/v4/packages/npm/

'//gitlab.com/api/v4/packages/npm/:_authToken'=NPM_TOKEN

The first line is scope declaration, we use instance level scope. Second line is authentication. After adding .npmrc you can run

npm install @my-org/packagename

All set. Just try importing the function and test if its works!

const add = require("@my-org/simpleadd");

console.log(add(2, 4));

Reference

https://docs.gitlab.com/ee/user/packages/npm_registry/

Emot's Space © 2025