Common component

This component needs to be present in each pipeline.

Components that perform authenticated GitLab operations use GITLAB_TOKEN. Configure it with a group service account when one of those components is included.

When GITLAB_TOKEN is set, each job startup summary shows its GitLab username as Token-User. If GitLab cannot authenticate the token, the job prints a warning and continues without the username.

External OCI registry credentials

GitLab Runner consumes DOCKER_AUTH_CONFIG before a job starts, so keep any credentials required for private job images and services there. CI Tools imports that configuration as the base of a unified, job-scoped registry file. Add credentials needed only by commands inside the job through CI_REGISTRY_AUTH_FILE; use either a protected file variable or literal Docker-compatible JSON.

• GitLab Runner pulls private images declared by an image or services keyword before the job starts.
• The container and buildah components authenticate base-image pulls and image pushes performed by Podman or Buildah.
• OCI-aware components such as oci-mirror reuse the merged credentials through skopeo, Helm, ORAS, and Cosign.

Registry names, including ports, must exactly match the names used by image references:

{
  "auths": {
    "registry.example.com:5000": {
      "auth": "BASE64_USERNAME_COLON_PASSWORD"
    }
  }
}

CI Tools merges DOCKER_AUTH_CONFIG, CI_REGISTRY_AUTH_FILE, and runtime logins from token and registry environment variables into /tmp/ci-tools/registry-auth/config.json. Later sources override matching registry entries from earlier sources. Podman, Buildah, skopeo, Helm, ORAS, and Cosign all use that unified file.

Prefer static auths entries over credential helpers unless the selected runners and every component image provide the helper binary. Grant each credential only the pull or push scopes required by the jobs that receive it. See GitLab's private container registry authentication guidance.

Usage

include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable

Common pipeline stages

The following stages are implemented by default:

Name	Description
.pre	default reserved special stage that is executed before all other stages and is used by some helper tasks
lint	Linting stage for all linting jobs before build
build	Build stage for all software builds
test	Test stage to validate all software builds
deploy	Deploy stage to ship a build to environments
release	Release stage to publish software releases
.post	default post pipeline stage in GitLab used by some helper tasks

Automatic retries

Jobs retry transient runner, API, stuck-runner, and server-enforced timeout failures up to two times. The retry conditions use GitLab's specific failure reasons introduced in GitLab 19.0 instead of the deprecated stuck_or_timeout_failure and job_execution_timeout aliases.

Validation

When validate-enabled is true, the .pre validation job checks common project settings. If KUBECONFIG is set as a file variable or base64 text variable, the job also validates that the credentials can reach the Kubernetes API server and have the namespace permissions required by CI Tools. The Kubernetes check is skipped when KUBECONFIG is unset.

Colored log messages

Use ci_log "[info] Message" to print the log-level prefix in blue while keeping the message in the terminal's normal color. Warning and error log lines are printed completely in yellow or red.

npm package proxy

Set the common component input npm-package-proxy to route npm package installation through a registry proxy such as Nexus. Components that install npm packages use npm defaults when the input is empty. You can still set CI_NPM_PACKAGE_PROXY directly when a project does not include the common component.

Load the library from a protected repository

A bootloader token is not required when loading the library with the default images in this library.

Set the global variable CI_BOOTLOADER_TOKEN in your GitLab instance when the CI Tools repository is private. Alternatively, pass a different variable through the common component's bootloader-token input. The component stages that input through an internal variable so child pipelines do not create a self-reference when the input uses CI_BOOTLOADER_TOKEN.

Inputs

Name	Description	Default	Type
---	---	---	---
bootloader	The internal bootloader to load the CI library. See scripts/bootloader.sh for details.	IyEvYmluL2Jhc2gKCiMgZ2VuZXJhdGUgaGFzaCBhbmQgcmVwbGFjZSBpbiB0ZW1wbGF0ZS9jb21tb24vdGVtcGxhdGUueW1sCiMgY2F0IHNjcmlwdHMvYm9vdGxvYWRlci5zaCB8IGJhc2U2NCAtdyAwCiMgZGVidWcKIyBDSV9ERUJVR19UUkFDRT10cnVlIC4vc2NyaXB0cy9ib290bG9hZGVyLnNoCgpmdW5jdGlvbiBjaV9sb2coKSB7CiAgbG9jYWwgbWVzc2FnZT0iJCoiCiAgbG9jYWwgY29sb3JfcmVzZXQ9JCdcMDMzWzBtJwogIGxvY2FsIGNvbG9yX2JsdWU9JCdcMDMzWzM0bScKICBsb2NhbCBjb2xvcl9yZWQ9JCdcMDMzWzMxbScKICBsb2NhbCBjb2xvcl95ZWxsb3c9JCdcMDMzWzMzbScKCiAgY2FzZSAiJHttZXNzYWdlfSIgaW4KICAgIFxbaW5mb1xdKikgcHJpbnRmICclcyVzJXMlc1xuJyAiJHtjb2xvcl9ibHVlfSIgIiR7bWVzc2FnZSUlXSp9XSIgIiR7Y29sb3JfcmVzZXR9IiAiJHttZXNzYWdlIypdfSIgOzsKICAgIFxbd2FyblxdKikgcHJpbnRmICclcyVzJXNcbicgIiR7Y29sb3JfeWVsbG93fSIgIiR7bWVzc2FnZX0iICIke2NvbG9yX3Jlc2V0fSIgOzsKICAgIFxbZXJyb3JcXSopIHByaW50ZiAnJXMlcyVzXG4nICIke2NvbG9yX3JlZH0iICIke21lc3NhZ2V9IiAiJHtjb2xvcl9yZXNldH0iIDs7CiAgICAqKSBwcmludGYgJyVzXG4nICIke21lc3NhZ2V9IiA7OwogIGVzYWMKfQoKaWYgW1sgLXYgMSBdXTsgdGhlbgogIGV4cG9ydCBDSV9UT09MU19WRVJTSU9OPSIkezF9IgplbHNlCiAgZXhwb3J0IENJX1RPT0xTX1ZFUlNJT049IiR7Q0lfVE9PTFNfVkVSU0lPTjotbWFpbn0iCmZpCgppZiBbWyAke0NJX0RFQlVHX1RSQUNFOi1mYWxzZX0gPT0gInRydWUiIF1dOyB0aGVuCiAgc2V0IC14CiAgc2V0IC1vIHBpcGVmYWlsCmZpCgpmdW5jdGlvbiBjaV9sb2FkX2xpYiB7CiAgbG9jYWwgYXJjaGl2ZQoKICB0bXBkaXI9JChta3RlbXAgLWQgLXAgL3RtcCk7CiAgZXhwb3J0IENJX1RPT0xTX0RJUj0iJHt0bXBkaXJ9IgogIGV4cG9ydCBDSV9TRVJWRVJfRlFETj0iJHtDSV9TRVJWRVJfRlFETjotZ2l0bGFiLmNvbX0iCgogICMgS2VlcCB0aGUgY29tcG9uZW50IGlucHV0IHNlcGFyYXRlIGZyb20gdGhlIGV4cG9ydGVkIHRva2VuIHZhcmlhYmxlIHNvIGEKICAjIGRlZmF1bHQgdGhhdCByZWZlcmVuY2VzIENJX0JPT1RMT0FERVJfVE9LRU4gY2Fubm90IGJlY29tZSBzZWxmLXJlZmVyZW50aWFsCiAgIyB3aGVuIEdpdExhYiBleHBhbmRzIGNoaWxkLXBpcGVsaW5lIHZhcmlhYmxlcy4KICBpZiBbWyAtbiAiJHtDSV9CT09UTE9BREVSX1RPS0VOX0lOUFVUOi19IiBdXTsgdGhlbgogICAgZXhwb3J0IENJX0JPT1RMT0FERVJfVE9LRU49IiR7Q0lfQk9PVExPQURFUl9UT0tFTl9JTlBVVH0iCiAgZmkKCiAgIyBTZXQgdG8gZW1wdHkgdmFsdWUgaWYgQ0lfQk9PVExPQURFUl9UT0tFTiB3YXMgbm90IGV4cGFuZGVkCiAgaWYgW1sgIiR7Q0lfQk9PVExPQURFUl9UT0tFTjotfSIgPX4gQ0lfQk9PVExPQURFUl9UT0tFTiBdXTsgdGhlbgogICAgZXhwb3J0IENJX0JPT1RMT0FERVJfVE9LRU49IiIKICBmaQoKICBjaV9ib290bG9hZGVyX2luc3RhbGxfY29tbWFuZCBjdXJsCiAgY2lfYm9vdGxvYWRlcl9pbnN0YWxsX2NvbW1hbmQgdGFyCiAgY2lfYm9vdGxvYWRlcl9pbnN0YWxsX2NvbW1hbmQgZ3ppcAoKICBpZiBbWyAteCAiJChjb21tYW5kIC12IGN1cmwpIiAmJiAteCAiJChjb21tYW5kIC12IHRhcikiICYmICggLW4gIiR7Q0lfQk9PVExPQURFUl9UT0tFTjotfSIgfHwgIiR7Q0lfU0VSVkVSX0ZRRE59IiA9PSAiZ2l0bGFiLmNvbSIgKSBdXTsgdGhlbgogICAgaWYgW1sgLWYgIi4vc2NyaXB0cy9saWJyYXJ5LnNoIiAmJiAtZiAiLi9zY3JpcHRzL2Jvb3Rsb2FkZXIuc2giIF1dOyB0aGVuCiAgICAgIGxvY2FsIGVuY29kZWRfcHJvamVjdF9wYXRoPSIke0NJX1BST0pFQ1RfUEFUSC8vXC8vJTJGfSIKICAgICAgbG9jYWwgdXJsPSJodHRwczovLyR7Q0lfU0VSVkVSX0ZRRE59L2FwaS92NC9wcm9qZWN0cy8ke2VuY29kZWRfcHJvamVjdF9wYXRofS9yZXBvc2l0b3J5L2FyY2hpdmUudGd6P3NoYT0ke0NJX1RPT0xTX1ZFUlNJT059IgogICAgZWxzZQogICAgICBsb2NhbCB1cmw9Imh0dHBzOi8vJHtDSV9TRVJWRVJfRlFETn0vYXBpL3Y0L3Byb2plY3RzL3hyb3ctcHVibGljJTJGY2ktdG9vbHMvcmVwb3NpdG9yeS9hcmNoaXZlLnRnej9zaGE9JHtDSV9UT09MU19WRVJTSU9OfSIKICAgIGZpCiAgICAjIEFsc28gd29ya3Mgd2l0aCB0YWcgYW5kIGJyYW5jaCBuYW1lcwogICAgYXJjaGl2ZT0iJHtDSV9UT09MU19ESVJ9L2NpLXRvb2xzLnRneiIKICAgIGlmIGNpX2Jvb3Rsb2FkZXJfY3VybCAiJHt1cmx9IiAiJHthcmNoaXZlfSIgXAogICAgICB8fCB7IFtbIC1uICIke0NJX0JPT1RMT0FERVJfVE9LRU46LX0iICYmICIke0NJX1NFUlZFUl9GUUROfSIgPT0gImdpdGxhYi5jb20iIF1dICYmIENJX0JPT1RMT0FERVJfVE9LRU49IiIgY2lfYm9vdGxvYWRlcl9jdXJsICIke3VybH0iICIke2FyY2hpdmV9IjsgfTsgdGhlbgogICAgICB0YXIgLXh6ZiAiJHthcmNoaXZlfSIgLUMgIiR7Q0lfVE9PTFNfRElSfSIgLS1zdHJpcC1jb21wb25lbnRzPTEgJiYgcmV0dXJuIDAKICAgIGZpCiAgZmkKICBjaV9ib290bG9hZGVyX2luc3RhbGxfY29tbWFuZCBnaXQKICBpZiBbWyAteCAiJChjb21tYW5kIC12IGdpdCkiIF1dOyB0aGVuCiAgICBpZiBbWyAtdiBDSV9KT0JfVE9LRU4gXV07IHRoZW4KICAgICAgYXV0aD0iZ2l0bGFiLWNpLXRva2VuOiR7Q0lfSk9CX1RPS0VOfUAiCiAgICBlbHNlCiAgICAgIGF1dGg9IiIKICAgIGZpCiAgICBsb2NhbCB1cmw9Imh0dHBzOi8vJHthdXRofSR7Q0lfU0VSVkVSX0ZRRE59L3hyb3ctcHVibGljL2NpLXRvb2xzLmdpdCIKICAgIGdpdCBjb25maWcgLS1nbG9iYWwgYWR2aWNlLmRldGFjaGVkSGVhZCBmYWxzZSB8fCB0cnVlCiAgICBpZiBbWyAiJHtDSV9UT09MU19WRVJTSU9OfSIgPX4gXlthLWYwLTldezQwfSQgXV07IHRoZW4KICAgICAgZ2l0IGNsb25lICR7dXJsfSAke0NJX1RPT0xTX0RJUn0KICAgICAgZ2l0IC1DICR7Q0lfVE9PTFNfRElSfSByZXNldCAke0NJX1RPT0xTX1ZFUlNJT059IC0taGFyZAogICAgZWxzZQogICAgICBnaXQgY2xvbmUgLS1icmFuY2ggJHtDSV9UT09MU19WRVJTSU9OfSAtLXNpbmdsZS1icmFuY2ggJHt1cmx9ICR7Q0lfVE9PTFNfRElSfQogICAgZmkKICAgIGlmIFtbICEgLWQgIiR7Q0lfVE9PTFNfRElSfSIgJiYgJENJX1NFUlZFUl9GUUROICE9ICJnaXRsYWIuY29tIiBdXTsgdGhlbgogICAgICBjaV9sb2cgIltlcnJvcl0gQ291bGQgbm90IGNsb25lIENJIHRvb2xzIGxpYnJhcnkgZnJvbSAke0NJX1NFUlZFUl9GUUROfSIKICAgICAgcmV0dXJuIDEKICAgIGZpCiAgICByZXR1cm4gMAogIGZpCiAgcmV0dXJuIDEKfQoKZnVuY3Rpb24gY2lfYm9vdGxvYWRlcl9jdXJsIHsKICBsb2NhbCB1cmw9IiR7MX0iCiAgbG9jYWwgb3V0cHV0PSIkezJ9IgoKICBpZiBbWyAtbiAiJHtDSV9CT09UTE9BREVSX1RPS0VOOi19IiBdXTsgdGhlbgogICAgY3VybCAtZiAtTCAtcyAtLWhlYWRlciAiUFJJVkFURS1UT0tFTjogJHtDSV9CT09UTE9BREVSX1RPS0VOOi19IiAtLXVybCAiJHt1cmx9IiAtLW91dHB1dCAiJHtvdXRwdXR9IgogIGVsc2UKICAgIGN1cmwgLWYgLUwgLXMgLS11cmwgIiR7dXJsfSIgLS1vdXRwdXQgIiR7b3V0cHV0fSIKICBmaQp9CgpmdW5jdGlvbiBjaV9ib290bG9hZGVyX2luc3RhbGxfY29tbWFuZCB7CiAgbG9jYWwgY29tbWFuZD0iJHsxfSIKICBsb2NhbCBwYWNrYWdlPSIkezI6LSRjb21tYW5kfSIKCiAgaWYgW1sgLXggIiQoY29tbWFuZCAtdiAiJGNvbW1hbmQiKSIgXV07IHRoZW4KICAgIHJldHVybiAwCiAgZmkKICBpZiBbWyAiJChpZCAtdSkiICE9ICIwIiBdXTsgdGhlbgogICAgcmV0dXJuIDAKICBmaQogIGlmIFtbIC14ICIkKGNvbW1hbmQgLXYgZG5mKSIgXV07IHRoZW4KICAgIGRuZiBpbnN0YWxsIC15ICIkcGFja2FnZSIKICBlbGlmIFtbIC14ICIkKGNvbW1hbmQgLXYgbWljcm9kbmYpIiBdXTsgdGhlbgogICAgbWljcm9kbmYgaW5zdGFsbCAteSAiJHBhY2thZ2UiCiAgZWxpZiBbWyAteCAiJChjb21tYW5kIC12IGFwdC1nZXQpIiBdXTsgdGhlbgogICAgYXB0LWdldCB1cGRhdGUgJiYgYXB0LWdldCBpbnN0YWxsIC15IC0tbm8taW5zdGFsbC1yZWNvbW1lbmRzICIkcGFja2FnZSIKICBmaQp9CgppZiBbWyAtZiAiLi9zY3JpcHRzL2xpYnJhcnkuc2giICYmIC1mICIuL3NjcmlwdHMvYm9vdGxvYWRlci5zaCIgXV07IHRoZW4KICBDSV9UT09MU19ESVI9JChyZWFscGF0aCAuLykKZWxzZQogIGNpX2xvYWRfbGliIHx8IHsKICAgIGNpX2xvZyAiW2Vycm9yXSBMb2FkaW5nIGxpYnJhcnk6IGhvc3QgJHtDSV9TRVJWRVJfRlFETn07IHZlcnNpb24gJyR7Q0lfVE9PTFNfVkVSU0lPTn0nOyBkaXJlY3RvcnkgJHtDSV9UT09MU19ESVJ9IgogICAgZXhpdCAxCiAgfQpmaQpzb3VyY2UgIiR7Q0lfVE9PTFNfRElSfS9zY3JpcHRzL2xpYnJhcnkuc2giCg==	string
bootloader-token	The deployment token to use for the bootloader to fetch the CI library from private repositories. Needs to be unmasked if used.	${CI_BOOTLOADER_TOKEN}	string
ca-bundle-path	The path to the CA bundle file with additional CA certificates.		string
npm-package-proxy	Optional npm registry proxy URL used by components that install npm packages.		string
registry	Registry to store container image releases in	$CI_REGISTRY	string
repo		registry.gitlab.com/xrow-public/ci-tools	string
repository-path	Repository to store container image releases in	$CI_PROJECT_PATH	string
stages	The stages available in the pipeline.	["lint","build","test","release","deploy"]	array
trivy-repository	The image repository to use for trivy.	ghcr.io/aquasecurity	string
validate-allow-failure	Should the pipeline continue if linting fails?	false	boolean
validate-enabled	Enable validation of the GitLab CI configuration	false	boolean
validate-needs	The jobs that the validate job depends on.	[]	array
validate-script	Enable validation of the GitLab CI configuration		string