Helm Mirror component

Mirrors a 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.

Use an oci:// source for an OCI chart. For a chart from a Helm repository, prefix the HTTPS URL with helm+ and append the chart name, for example helm+https://charts.example.com/stable/example. The target must use an oci:// reference. The chart is published as <target>/<chart>:<version> and images as <target>/images/<repository>:<tag>; no charts/ prefix is added. Plain HTTP repositories and local chart directories are unsupported.

Registry authentication

Configure source and destination credentials with the central registry authentication guide.

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
      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/cert-manager:v1.18.2. Images are copied below $CI_REGISTRY_IMAGE/disconnected/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.

To mirror a chart from a Helm repository, keep the same target and replace the source and version:

source: helm+https://raw.githubusercontent.com/DefectDojo/django-DefectDojo/helm-charts/defectdojo
version: 1.9.53

The component adds https://raw.githubusercontent.com/DefectDojo/django-DefectDojo/helm-charts as a temporary Helm repository and pulls its defectdojo chart. The chart is still published to the configured OCI target.

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.

Mirror references with a tag and digest

Use a tag-only or digest-only reference when configuring a workload image. If a rendered image contains both, the component emits this warning:

Docker references with both a tag and digest are currently not supported

The component copies both separate forms: the tag-selected image keeps its tag, and the digest-selected image uses the existing sha256-<source-digest> target tag. Registry ports are preserved when separating the source references. The tag can identify different content from the digest; neither copy claims that a combined destination reference is supported.

Inspect the separate source/target entries after a successful mirror job:

jq -r '.[] | [.source, .target] | @tsv' helm-mirror/images.json

Choose the appropriate mirrored image when configuring chart values. The component does not rewrite the workload image reference or publish assumed destination digests. Dry runs show the mapping and warning without copying.

Update repository chart dependencies

After a successful mirror, update-dependencies defaults to true. The job finds tracked parent Chart.yaml files that depend on the mirrored chart. A match needs both the chart name and its explicit source repository URL, or the configured target OCI namespace. Dependency aliases are preserved. Bundled charts below a charts/ directory are not treated as parent charts.

For each matching parent, the job sets the dependency repository to target and its version to the published chart metadata version. It runs helm dependency update --skip-refresh to refresh Chart.lock and replace bundled subchart archives. Helm may also refresh other dependencies within that parent's existing version constraints, so use exact versions when those must remain pinned.

The job then commits only the matching parents' chart metadata, lock files, and bundled charts, and pushes with GitLab option ci.skip to prevent a loop. It starts from the current remote branch tip in a separate Git checkout, leaving the pipeline checkout and unrelated staged files unchanged. A concurrent remote commit causes an ordinary push rejection; the job never force-pushes over it.

Branch pipelines update their branch. Same-project merge request pipelines update their source branch. Tag pipelines update CI_DEFAULT_BRANCH, not the tag. Cross-project merge request write-back is rejected. The configured GITLAB_TOKEN or GIT_SSH_KEY must permit writes to the selected branch; protected branches still enforce their normal permissions.

No match or an already identical mirrored dependency produces no commit or push. A dry run never updates dependencies. Set update-dependencies: false to mirror artifacts without changing the repository:

inputs:
  source: oci://quay.io/jetstack/charts/cert-manager
  version: v1.18.2
  target: oci://$CI_REGISTRY_IMAGE/disconnected
  update-dependencies: false

Repository aliases such as @stable cannot be matched to an explicit source URL. Use the repository URL in the dependency declaration when you want write-back.

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 reference. Use an oci:// reference or a helm+https:// repository URL ending in the chart name.		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 directly below it, without a charts/ prefix.		string
update-dependencies	Update matching repository chart dependencies and push with ci.skip after mirroring.	true	boolean
value-files	Helm values files used when discovering rendered workload images.	[]	array
version	Source Helm chart version.		string

Registry authentication​

Usage​

Mirror references with a tag and digest​

Update repository chart dependencies​

Inputs​

Registry authentication

Usage

Mirror references with a tag and digest

Update repository chart dependencies

Inputs