Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Packages and Registry

Package Registry

Publish and install your own libraries with the GitLab Package Registry: npm, PyPI, Maven and generic packages, authentication with job tokens, versioning and access rules.

Teams reuse code: a shared validation library, an internal command-line tool, a design system. Copying files between repositories does not scale, and publishing company code to a public registry is out of the question. The GitLab Package Registry is a private store for packages that sits beside your code. You publish from a pipeline and install the result with the usual package manager, using GitLab for permissions.

This lesson explains how packages are addressed, how to publish and install the most common formats, how authentication works and how to manage versions. The package managers need a GitLab server, so the commands are read-only; the examples are JavaScript models of the addressing and version rules.

Supported formats

GitLab can store npm, PyPI, Maven, Gradle, NuGet, Composer, Conan, Debian, Helm charts, RubyGems, Go, Terraform modules and generic packages (any files). The generic type is a good starting point to understand the pattern, since it is plain HTTP.

The menu entry is under Deploy > Package Registry in the project or group. A package belongs to a project, but it can be installed from a group or instance-wide address, which is useful when many projects publish to one place.

Publishing a generic package

A generic package is a named, versioned set of files, uploaded with a PUT request:

YAML
publish_binary:
  stage: deploy
  image: curlimages/curl:latest
  script:
    - |
      curl --fail --header "JOB-TOKEN: $CI_JOB_TOKEN" \
        --upload-file build/tool-linux-amd64 \
        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/mytool/${CI_COMMIT_TAG}/tool-linux-amd64"
  rules:
    - if: $CI_COMMIT_TAG

The address pattern is /projects/<id>/packages/generic/<package name>/<version>/<file name>. CI_JOB_TOKEN gives the job permission for its own project, with no personal token. To download from another job or machine, use the same URL with a GET request and an appropriate token.

npm packages

For JavaScript libraries, add an .npmrc that tells npm which registry serves your scope and which token to use:

INI
@acme:registry=https://gitlab.example.com/api/v4/projects/123/packages/npm/
//gitlab.example.com/api/v4/projects/123/packages/npm/:_authToken=${CI_JOB_TOKEN}

Then publish from CI:

YAML
publish_npm:
  stage: deploy
  image: node:22
  script:
    - echo "@acme:registry=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc
    - echo "${CI_API_V4_URL#https:}/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
    - npm publish
  rules:
    - if: $CI_COMMIT_TAG

Two rules to remember: the package name in package.json must use your scope (@acme/ui-kit), and the scope must match the one in .npmrc. A repeated version cannot be published again (npm packages are immutable by design). The .npmrc lines above are an illustration; follow the exact format in the documentation for your GitLab version, because the URL prefix handling varies.

PyPI packages

YAML
publish_pypi:
  stage: deploy
  image: python:3.13
  script:
    - pip install build twine
    - python -m build
    - TWINE_USERNAME=gitlab-ci-token TWINE_PASSWORD="$CI_JOB_TOKEN"
      python -m twine upload --repository-url "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi" dist/*
  rules:
    - if: $CI_COMMIT_TAG

Consumers install with pip install mylib --index-url https://__token__:<token>@gitlab.example.com/api/v4/projects/123/packages/pypi/simple. Put the token in the environment, not in a file in the repository.

Maven and others

Maven projects add a <repository> and <distributionManagement> section to pom.xml and a server entry with credentials (a settings.xml using the Job-Token header in CI) and then run mvn deploy. NuGet, Composer and Helm follow the same shape: a registry URL, a token, a publish command. Learn the pattern once, then look up the format-specific lines.

Authentication choices

Token Use
CI_JOB_TOKEN Publishing or installing inside a pipeline of the same project (or allowed projects)
Deploy token (read_package_registry, write_package_registry) A server or a customer that installs packages without a user account
Personal or project access token (api or read_api scope) Developers on their own machines; prefer project access tokens with an expiry

For installs across projects, the job token allowlist in the consuming project must permit it. Keep scopes minimal and always set expiry dates.

Package visibility and duplicates

Access follows the project's visibility and roles: a Guest on a private project cannot install, a Reporter can. For npm, Maven and PyPI GitLab can also forbid duplicate versions in settings (generic packages can allow replacement). Publishing the same version twice with different content is dangerous, since users cannot tell which copy they have, so keep duplicates forbidden.

A related risk is dependency confusion: if your internal package name also exists on the public registry, a package manager may install the public one. Using a scope (@acme/...) or a configured private index prevents this.

Stand-in: building addresses and picking a version

The first example builds the generic-package URL from the variables, so you can see how the parts fit.

JS Generic package URLs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example resolves a version range from a list of published versions, the way a package manager picks the newest version that satisfies a caret range. It also shows why a published version must never change.

JS Choosing a version

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which token lets a pipeline publish a package to its own project without a personal credential?

    The job token is created for the running job, limited to the pipeline's project (and allowed projects), and expires when the job ends.
  2. 2. What is the address pattern for a generic package file?

    The generic API sits under the project and has package name, version and file name segments.
  3. 3. Why use an npm scope such as @acme?

    .npmrc routes @acme to GitLab, so npm does not fetch a public package with the same bare name.
  4. 4. Why forbid duplicate package versions?

    A version number is a promise of fixed content. Republishing changed content breaks reproducible builds.

Summary

  • The Package Registry stores npm, PyPI, Maven, NuGet, Composer, Helm, generic and other packages next to the code.
  • Publish from a tagged pipeline using CI_JOB_TOKEN; consumers use deploy or access tokens with narrow scopes.
  • Use scopes or private indexes to avoid dependency confusion, and forbid duplicate versions.
  • Versions are immutable: to change a package, publish a new version.

Next: Releases and Semantic Versioning