Package component

The package component builds and optionally publishes packages from a project directory.

Supported package types

`type`	Red Hat Hardened Image catalog
`python`	Python
`nodejs`	Node.js
`dotnet`	.NET SDK
`go`	Go
`maven`	OpenJDK
`gradle`	OpenJDK
`php`	PHP
`ruby`	Ruby
`rust`	Rust
`c`	GCC Toolset

Package versions and publish tags

Package builds should use predictable versions and publish tags so consumers can choose a stable release, a default-branch build, or a branch/MR build without guessing which artifact they are installing.

Use this matrix for package types that generate CI package versions or publish tags, including npm packages:

General Matrix

Git ref	Tagged	Resulting package versions and tags
`main`	yes	`x.x.x` SemVer release tag, plus `0.0.0` as latest stable
`main`	no	`main`, `0.0.0+main`, `0.0.0+<commit_hash>`
merge request branch	no	`0.0.0+<commit_hash>`
`other-branch`	yes	`x.x.x` SemVer release tag
`other-branch`	no	`0.0.0+<commit_hash>`

npm Matrix

Git ref	Tagged	Package version	npm dist-tag
`main`	yes, newest stable release	`x.x.x` SemVer release tag	`latest`
`main`	yes, older stable release	`x.x.x` SemVer release tag	`release-x.x.x`
`main`	no	`0.0.0-sha.<commit_hash>`	`sha.<commit_hash>`
merge request branch	no	`0.0.0-sha.<commit_hash>`	`sha.<commit_hash>`
`other-branch`	yes, prerelease	`x.x.x-<prerelease>` SemVer prerelease tag	`prerelease-x.x.x-<prerelease>`
`other-branch`	no	`0.0.0-sha.<commit_hash>`	`sha.<commit_hash>`

npm dist-tags cannot be valid SemVer ranges, so generated prerelease versions such as 0.0.0-sha.<commit_hash> are published with the matching install tag sha.<commit_hash>.

npm scope validation

GitLab instance-level npm installs require scoped package names where @scope matches the root namespace that hosts the package. For example, packages hosted below xrow-public/... must use a package name such as @xrow-public/package-name.

When registry: instance is selected, the component enforces that convention before publishing and publishes through the GitLab group npm endpoint. When registry: project or registry: group is selected, the component only warns on a scope mismatch because those endpoints can still publish packages whose scope differs from the root namespace.

Publish to npmjs.com with trusted publishing

Use npm trusted publishing to publish from GitLab.com without storing a long-lived npm token. Before using it:

Configure GitLab CI/CD as a trusted publisher in the package settings on npmjs.com. The namespace, project name, and top-level CI file path must match the GitLab project.
Use a GitLab.com shared runner. npm trusted publishing does not support self-hosted runners.
Use Node.js 22.14.0 or later and npm 11.5.1 or later.

Trusted publishing is disabled by default. Set trusted-publishing: true to opt in. The package component requests NPM_ID_TOKEN with the npm:registry.npmjs.org audience and SIGSTORE_ID_TOKEN with the sigstore audience. Configure the remote registry without a token:

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/package@stable
    inputs:
      name: npm-package
      path: .
      type: nodejs
      registry: remote
      remote-registry-url: https://registry.npmjs.org/
      trusted-publishing: true
      image: registry.access.redhat.com/hi/nodejs:26.9.0-builder-1789612397@sha256:614e489f0e686023b082bb11acbf53072a86fbab41475dfea0138951ec90bb1f

On a tag pipeline, npm exchanges NPM_ID_TOKEN for a short-lived publish credential. The package job exits successfully without building or publishing when trusted publishing is enabled and CI_RUNNER_TAGS does not start with saas-. This prevents trusted publishing from running on a self-hosted runner.

Merge request pipelines with remote-registry-token configured publish remote npm packages with commit-scoped versions and tags. Without trusted-publishing: true, set remote-registry-token to the name of a masked CI/CD variable such as NPM_TOKEN. The GitLab project, group, and instance registries continue to use CI_JOB_TOKEN.

Java packages

Gradle projects are handled with type: gradle and must provide an executable gradlew. Maven projects are handled with type: maven; the component prefers an executable mvnw and otherwise uses mvn from the builder image.

Auto detection selects Maven when the package path contains pom.xml and Gradle when it contains gradlew.

.NET packages

.NET projects are handled with type: dotnet. Auto detection selects dotnet when the package path contains a .csproj file or packages.config.

For GitLab package registry restores, the component configures a NuGet package source named GitLab. If you provide your own NuGet.Config, use the same source name:

<packageSources>
  <clear />
  <add key="GitLab" value="https://gitlab.com/api/v4/projects/<project-id>/packages/nuget/index.json" />
</packageSources>

Credentials for that source are read from the standard NuGet environment variable NuGetPackageSourceCredentials_GitLab. When it is not set, the component fills it from CI_JOB_TOKEN for GitLab CI restores. Publishing uses NUGET_API_KEY when available and otherwise falls back to CI_JOB_TOKEN.

Inputs

Name	Description	Default	Type
---	---	---	---
image	Builder image to use for the build package jobs. Select Red Hat Hardened Image from the Red Hat Catalog (https://images.redhat.com/).		string
name	Name for the package/project.	${CI_PROJECT_NAME}	string
needs	The jobs that this job depends on.	[]	array
path	Should the pipeline fail if the test fails?	.	string
registry	Selects the registry to use for the package.	project	string
remote-registry-token	The authentication token for the remote registry.		string
remote-registry-url	The URL of the remote registry to use for the package.		string
remote-registry-user	The username for the remote registry.		string
rules	The jobs that this job depends on.	[{"if":"$CI_PIPELINE_SOURCE == \"schedule\"","when":"never"},{"if":"$CI_PIPELINE_SOURCE == \"merge_request_event\"","when":"never"},{"when":"on_success"}]	array
scanning-allow-failure	Should the pipeline fail if scanning the built package fails?	true	boolean
scanning-enabled	Should the package be scanned?	true	boolean
scanning-ignore-unfixed	Exclude vulnerabilities that do not have a fix available.	true	boolean
scanning-severity	What level of severity should cause scanning of the built package to fail?	CRITICAL	string
stage	The pipeline stage that the job will belong to.	build	string
tags	The runners that this job depends on.	[]	array
trusted-publishing	Use npm trusted publishing for registry.npmjs.org instead of a remote registry token.	false	boolean
type		auto	string

Supported package types​

Package versions and publish tags​

General Matrix​

npm Matrix​

npm scope validation​

Publish to npmjs.com with trusted publishing​

Java packages​

.NET packages​

Inputs​