Transfer Helm Charts with OCM

Goal#

Transfer a component version that contains a Helm chart resource sourced from a Helm repository (type helmChart with helm/v1 access) to an OCI registry. This guide does not cover charts that are already stored as OCI artifacts.

Prerequisites#

• OCM CLI installed
• Write access to a target OCI registry with credentials configured
• A component version containing a Helm chart resource (stored in a CTF archive or OCI registry)

Steps#

Helm charts stored as ociImage

If your existing component version contains a Helm chart stored as an ociImage resource rather than a helmChart with helm/v1 access, you need to create a new component version using the helmChart type as shown below. This guide only covers the transfer of Helm charts sourced from Helm repositories.

1. Create a component version with a Helm chart resource#

   If you already have a component version containing a Helm chart with helm/v1 access, skip to the next step.

   Create a constructor.yaml that references a chart from a Helm repository:

   components:
     - name: example.com/my-app
       version: 1.0.0
       provider:
         name: example.com
       resources:
         - name: my-chart
           version: 1.0.0
           type: helmChart
           access:
             type: helm/v1
             helmRepository: https://charts.example.com
             helmChart: my-chart-1.0.0.tgz

   Add the component version to a CTF archive:

   ocm add cv --repository ctf::<path/to/archive> \
     --constructor constructor.yaml \
     --skip-reference-digest-processing

Why –skip-reference-digest-processing?

The --skip-reference-digest-processing flag is required because the helm/v1 access type currently cannot be fully resolved during add cv. The chart is not downloaded at this stage, so digest calculation is not possible. The digests are computed later during transfer when the chart is actually fetched. Full Helm support is being tracked as a future feature in ocm-project#911.

2. Transfer the component version#

   Transfer the component version to the target registry. Use --copy-resources to include the Helm chart and --upload-as ociArtifact to store it as a standalone OCI artifact in the target registry.

   Note: The --upload-as flag is a temporary solution. It will be superseded by the upcoming transfer specification. See ocm-project#925 for details.

   ocm transfer cv \
     --copy-resources \
     --upload-as ociArtifact \
     ctf::<path/to/archive>//<component-name>:<version> \
     <target-registry>

   During transfer, the Helm chart is always converted to an OCI artifact. With --upload-as ociArtifact, this artifact is uploaded as a separate image in the target registry. The component descriptor references it via an imageReference (e.g., ghcr.io/my-org/charts/my-chart:1.0.0), making it independently addressable and pullable with helm pull. For more details on how transfers and resource handling work, see Transfer and Transport.

   Alternatively, --upload-as localBlob embeds the chart directly in the component version’s blob store. This keeps the chart coupled to the component version but means it is not independently addressable in the registry and cannot be pulled with the Helm CLI.

   To find the imageReference, inspect the component descriptor:

   ocm get cv <target-registry>//<component-name>:<version> -o yaml

   In the output, look for the resources[].access.imageReference field:

   resources:
     - name: my-chart
       type: helmChart
       access:
         type: ociArtifact/v1
         imageReference: ghcr.io/my-org/charts/my-chart:1.0.0

   Use the imageReference value with Helm’s OCI support:

   helm pull oci://ghcr.io/my-org/charts/my-chart --version 1.0.0

3. Verify the transfer#

   Confirm the component version is available in the target registry:

   ocm get cv <target-registry>//<component-name>:<version>

   Download the chart resource to verify it was transferred correctly:

   ocm download resource \
     <target-registry>//<component-name>:<version> \
     --identity name=my-chart \
     --output ./downloaded

Transfer between registries#

To transfer a Helm chart component version from one OCI registry to another, use the source registry reference directly:

ocm transfer cv \
  --copy-resources \
  --upload-as ociArtifact \
  <source-registry>//<component-name>:<version> \
  <target-registry>

Tips#

• If provenance files (.prov) are present in the Helm repository, they are automatically included in the transfer.
• If you need to transfer recursively, add --recursive to include all transitively referenced component versions.
• For air-gapped environments, first transfer to a CTF archive, move it across the boundary, then import into the target registry. See Transfer Components Across an Air Gap.

Related documentation#

• Transfer and Transport – Understand the transfer model and resource handling
• Transfer Components Across an Air Gap – Air-gapped transfer workflows
• Download Resources from Component Versions – Download individual resources