Skip to main content

Publishing Packages

You can use a package only after publishing it, making it accessible to other packages. ADITO manages this via a package registry hosted on its GitLab. You can also use any other compatible package registry. This document is written for GitLab, but the principles apply to other registries as well.

tip

Learn more in the documentation about npm package registries on GitLab.

Preparing a Package for Release​

Before releasing a package:

  • Set the version in package.json following SemVer. Keep in mind:
    • Minimize major releases; dependents must adapt and release majors, too.
    • Integrate a new major only when dependents are compatible.
    • Changing or restricting version ranges is a major change, except:
      • Removing a dependency.
      • Extending a range (e.g., ^1.0.0 → ^1.0.0 || ^2.0.0), which remains backward compatible for dependents.
  • CHANGELOG.md: Replace "Unreleased" with the release date and version; ensure all changes since the last release are documented.
  • package.json: Remove prerelease version tags; update dependencies and their versions if needed.
  • Run npm install to lock updated dependencies.
  • Commit changes and push.
  • Create a Git tag with the version number and push the tag.

Publishing the Package​

After preparation, publish to the package registry.

tip

For details on npm publish, see the official docs.

Automated Publishing​

Packages should typically be published automatically via a GitLab CI/CD pipeline.

A common pattern is: when a tag is pushed, a job authenticates to the npm registry and runs npm publish.

Before publishing a package in GitLab, ensure the following:

  • The GitLab user has at least Developer permissions on the project and the containing group.
  • The Package Registry is enabled in the project: Settings → General → Visibility, Project Features & Permissions → Package Registry.

For automated publishing you can either use a project-specific pipeline or a shared pipeline. Some shared standard pipelines are available at https://gitlab.adito.de/xrm-modules/ci-pipelines for tag-based publishing, ESLint, security scans, and Liquibase validation. To use the shared pipeline:

  • Enable CI/CD: Settings → General → Visibility, project features, permissions → CI/CD
  • Under Settings → CI/CD → General Pipeline, set the pipeline file path, for example: 
    .gitlab-ci.yml@xrm-modules/ci-pipelines

A general pipeline might look like this:

Example GitLab CI/CD Pipeline Configuration
deploy_on_gitlab_project:
  stage: deploy
  rules:
   - if: '$CI_COMMIT_TAG'
  image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:22.13
  variables:
    GITLAB_REGISTRY: ${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/
    GITLAB_TOKEN: ${CI_JOB_TOKEN}
  script:
    - echo "//${GITLAB_REGISTRY}:_authToken=${GITLAB_TOKEN}" > .npmrc
    - npm publish --registry=https://${GITLAB_REGISTRY}

Notes:

  • This example publishes the package within the same GitLab project.
  • Consider adding a .npmignore or files in package.json to control which files are published.
tip

For further customization, consult the GitLab CI/CD documentation and the npm publish documentation.

Manual Publishing​

You should prefer automation. Use manual publishing only in exceptional cases.

Authenticate to the Registry​

You must authenticate before publishing. For GitLab's npm registry, see the official guide: Authenticate to the Package Registry.

Common options:

  • Login with a token: 
    npm config set //gitlab.example.com/api/v4/projects/PROJECT_ID/packages/npm/:_authToken TOKEN
  • Or create a project-scoped .npmrc (do not commit secrets).
danger

Never commit credentials or access tokens. Do not commit .npmrc containing Personal Access Tokens (PAT). Remove tokens or use placeholders before committing, or add .npmrc to .gitignore.

Publish​

After authentication, run npm publish with the necessary options.

tip

For more information on npm publish, see the official docs.