Helm Mirror component
Mirrors an OCI Helm chart together with every workload image found in its rendered Kubernetes manifests. The job publishes the chart below the target OCI namespace and copies discovered images into a deterministic images/ tree. It also saves the rendered manifests and a source-to-target mapping as job artifacts.
The source and target must use oci:// references. HTTP chart repositories and local chart directories are intentionally unsupported.
Variables
| Name | required | type | Hints |
|---|---|---|---|
| CI_REGISTRY_USER | required for private GitLab targets | string | GitLab container registry user. Provided by GitLab CI. |
| CI_REGISTRY_PASSWORD | required for private GitLab targets | string | GitLab container registry password. Provided by GitLab CI. |
When GITHUB_TOKEN is available, the job also authenticates Helm and skopeo to ghcr.io. Private registries outside the current GitLab instance can be configured with the standard DOCKER_AUTH_CONFIG variable documented by the common component.
Usage
include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/helm-mirror@stable
inputs:
name: cert-manager
source: oci://quay.io/jetstack/charts/cert-manager
version: v1.18.2
target: oci://$CI_REGISTRY_IMAGE/disconnected/charts
value-files:
- deploy/cert-manager-values.yaml
set-parameters:
- startupapicheck.enabled=false
For the example above, the chart is published as $CI_REGISTRY_IMAGE/disconnected/charts/cert-manager:v1.18.2. Images are copied below $CI_REGISTRY_IMAGE/disconnected/charts/images/, preserving their source repository paths after the registry host. The helm-mirror/images.json artifact records every exact source and target reference so deployment configuration can point the chart at the mirrored images.
Only images represented by scalar image: fields in rendered Kubernetes resources are discovered. Use value-files and set-parameters to render optional workloads that must be included. Images embedded in command arguments, ConfigMaps, hooks disabled by values, or other free-form strings are not inferred.
Set dry-run: true to validate chart rendering and inspect the generated mapping without copying artifacts. Source signatures are removed from workload images by default because many destination registries cannot store them; set remove-signatures: false when they must be preserved and the target supports signature attachments.
Inputs
| Name | Description | Default | Type |
| --- | --- | --- | --- |
| dry-run | Discover images and produce the mapping artifact without copying the chart or images. | false | boolean |
| name | Name suffix for the Helm mirror job. | chart | string |
| needs | Jobs that the Helm mirror job depends on. | [] | array |
| remove-signatures | Remove source image signatures while copying workload images. | true | boolean |
| rules | Rules that control when the Helm mirror job runs. | [{"if":"$CI_COMMIT_TAG","when":"always"},{"when":"never"}] | array |
| set-parameters | Helm --set parameters used when discovering rendered workload images. | [] | array |
| source | Source Helm chart OCI reference, including the oci:// prefix. | string | |
| stage | Pipeline stage for the Helm mirror job. | deploy | string |
| tags | Runners that the Helm mirror job depends on. | [] | array |
| target | Destination OCI namespace, including the oci:// prefix. The chart and an images/ tree are created below it. | string | |
| value-files | Helm values files used when discovering rendered workload images. | [] | array |
| version | Source Helm chart version. | string |