Package component

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

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_hasht>
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.

.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. Like a S2I Image from the Red Hat Catalog.		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-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
type		auto	string