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.
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
NPM_TOKEN
here can be get by go to Settings > Repository > Deploy tokens, then creates a new token withread_package_registry
andwrite_package_registry
scopes.
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/