Overriding Helm Chart Repository URLs in Renovate

This article explains how Renovate processes different repository formats in Helm Chart.yaml files and how to configure Renovate to redirect version lookups to your internal registry (e.g., Artifactory, Nexus).

Overview

Helm charts can reference dependencies using three repository formats:

Format	Example	Renovate Behavior
HTTPS	`https://charts.bitnami.com/bitnami`	Uses the URL directly for lookups
OCI	`oci://ghcr.io/myorg`	Treats the chart as a container image
Alias	`@myrepo` or `alias:myrepo`	Resolves the alias before lookup

Each format requires a different Renovate configuration approach to redirect lookups.

Scenario 1: HTTPS Repositories

Chart.yaml Example

YAML

apiVersion: v2
name: my-application
version: 1.0.0
dependencies:
  - name: redis
    version: 17.0.0
    repository: https://charts.bitnami.com/bitnami
  - name: postgresql
    version: 12.0.0
    repository: https://charts.bitnami.com/bitnami

Renovate Configuration

Use registryUrls within packageRules to redirect lookups. Glob patterns allow matching multiple charts:

JSON

{
  "packageRules": [
    {
      "matchManagers": ["helmv3"],
      "matchDatasources": ["helm"],
      "matchPackageNames": ["redis*", "postgresql*"],
      "registryUrls": ["https://artifactory.example.com/helm-bitnami"]
    }
  ]
}

This configuration matches redis, redis-cluster, postgresql, postgresql-ha, and any other chart names starting with those prefixes. Remove the "matchPackageNames" configuration if you wish to map all HTTPS-based repositories in Helm charts.

Scenario 2: OCI Repositories

An OCI (Open Container Initiative) repository stores Helm charts as container images, allowing them to be hosted in standard container registries like GitHub Container Registry, http://Quay.io , or Docker Hub. These repositories use the oci:// protocol prefix.

Chart.yaml Example

YAML

apiVersion: v2
name: my-application
version: 1.0.0
dependencies:
  - name: my-chart
    version: 2.0.0
    repository: oci://ghcr.io/my-org/helm-charts
  - name: another-chart
    version: 1.5.0
    repository: oci://quay.io/some-org

Renovate Configuration

OCI repositories embed the registry in the package name. Use overridePackageName to rewrite the registry:

JSON

{
  "packageRules": [
    {
      "matchManagers": ["helmv3"],
      "matchDatasources": ["docker"],
      "matchPackageNames": ["/^ghcr\\.io\\/my-org\\//"],
      "overridePackageName": "{{replace 'ghcr.io/my-org' 'artifactory.example.com/helm-oci' packageName}}"
    },
    {
      "matchManagers": ["helmv3"],
      "matchDatasources": ["docker"],
      "matchPackageNames": ["/^quay\\.io\\/some-org/"],
      "overridePackageName": "{{replace 'quay.io/some-org' 'artifactory.example.com/helm-quay' packageName}}"
    }
  ]
}

For a single specific chart:

JSON

{
  "packageRules": [
    {
      "matchManagers": ["helmv3"],
      "matchDatasources": ["docker"],
      "matchPackageNames": ["ghcr.io/my-org/helm-charts/my-chart"],
      "overridePackageName": "artifactory.example.com/helm-oci/my-chart"
    }
  ]
}

Note: OCI-based charts use the docker datasource, which is why matchDatasources: ["docker"] is specified.

Scenario 3: Alias Repositories

An alias repository is a shorthand reference (prefixed with @ or alias:) that points to a Helm repository URL configured locally via helm repo add. This allows Chart.yaml files to reference repositories by name rather than full URL.

Chart.yaml Example

YAML

apiVersion: v2
name: my-application
version: 1.0.0
dependencies:
  - name: nginx
    version: 13.0.0
    repository: "@bitnami"
  - name: kafka
    version: 22.0.0
    repository: "alias:confluent"

Renovate Configuration

Use registryAliases to define what each alias resolves to:

JSON

{
  "registryAliases": {
    "bitnami": "https://artifactory.example.com/helm-bitnami",
    "confluent": "https://artifactory.example.com/helm-confluent"
  }
}

For OCI-based aliases:

JSON

{
  "registryAliases": {
    "my-oci-repo": "oci://artifactory.example.com/helm-oci"
  }
}

Important:
Do not include the @ or alias: prefix in the configuration key
Alias matching is case-sensitive and exact (no partial matching)

Combined Configuration Example

If your project uses all three repository formats:

Chart.yaml

YAML

apiVersion: v2
name: my-application
version: 1.0.0
dependencies:
  # HTTPS repository
  - name: redis
    version: 17.0.0
    repository: https://charts.bitnami.com/bitnami
  
  # OCI repository
  - name: my-service
    version: 2.0.0
    repository: oci://ghcr.io/my-org/charts
  
  # Alias repository
  - name: monitoring
    version: 45.0.0
    repository: "@prometheus"

renovate.json

JSON

{
  "registryAliases": {
    "prometheus": "https://artifactory.example.com/helm-prometheus"
  },
  "packageRules": [
    {
      "description": "Redirect Bitnami HTTPS charts",
      "matchManagers": ["helmv3"],
      "matchPackageNames": ["redis"],
      "registryUrls": ["https://artifactory.example.com/helm-bitnami"]
    },
    {
      "description": "Redirect OCI charts from ghcr.io",
      "matchManagers": ["helmv3"],
      "matchDatasources": ["docker"],
      "matchPackageNames": ["/^ghcr\\.io\\/my-org\\//"],
      "overridePackageName": "{{replace 'ghcr.io/my-org' 'artifactory.example.com/helm-oci' packageName}}"
    }
  ]
}

Quick Reference

Repository Format	Configuration Option	Scope
HTTPS	`registryUrls`	Per package via `packageRules`
OCI	`overridePackageName`	Per package via `packageRules`
Alias (`@` / `alias:`)	`registryAliases`	Global or per manager

Overview

Scenario 1: HTTPS Repositories

Chart.yaml Example

Renovate Configuration

Scenario 2: OCI Repositories

Chart.yaml Example

Renovate Configuration

Scenario 3: Alias Repositories

Chart.yaml Example

Renovate Configuration

Combined Configuration Example

Chart.yaml

renovate.json

Quick Reference

Additional Resources