Docs

Helm

Description

The helm crawler looks recursively for all Helm charts from a specific root directory. A directory is treated as a chart root when it contains a Chart.yaml or Chart.yml file.

For each chart it performs two independent kinds of update:

  • Chart dependencies declared in Chart.yaml. Disable with ignorechartdependency: true.

  • Container images declared in values.yaml or values.yml. Disable with ignorecontainer: true.

This crawler is enabled by default, so it can be used either automatically by running updatecli diff from a directory containing the files to update, or by providing a manifest. The automatic discovery behavior can be tuned by providing a YAML manifest with a helm crawler in top-level directive autodiscovery as explained in the "Autodiscovery" page.

Container image patterns

Updatecli looks for the following patterns in the chart values, where registry is optional:

image:
  registry: ghcr.io
  repository: updatecli/updatecli
  tag: 0.37.0

or

images:
  backend:
      repository: ghcr.io/updatecli/updatemonitor
      tag: 0.1.0
  front:
      repository: ghcr.io/updatecli/updatemonitor-ui
      tag: 0.1.0

An image with no tag is assumed to be latest. An image with no repository is skipped. A digest already present in repository, such as image@sha256:…​, is stripped before the lookup.

Generated manifests

Both flavours write through the helmchart target rather than editing files directly, so a chart is repackaged whenever one of its dependencies or images is bumped.

FlavourManifest shape

Chart dependency

A helmchart source for the latest dependency version, yaml conditions asserting the dependency name and repository still match, and a helmchart target writing $.dependencies[i].version.

Container image

A dockerimage source for the latest tag, yaml conditions asserting the registry and repository, and a helmchart target writing the tag. When digest pinning is enabled a dockerdigest source is added and the digest is written too.

Two parameters control what the target does to the chart itself:

  • skippackaging - when true, the chart is not repackaged.

  • versionincrement - how the chart’s own version in Chart.yaml is bumped in response to the change. Accepts a comma-separated list of none, major, minor, patch. Empty by default, meaning the chart version is left alone.

Digest pinning

digest defaults to true, so image updates resolve and write an immutable digest alongside the tag. Set digest: false to track the tag only.

Authentication

Use auths to reach private registries, keyed by registry URL without a scheme, accepting either a token or a username/password pair. When it is empty Updatecli falls back to the ambient OCI credentials, such as those written by docker login.

Version filtering

If unspecified, the version filter defaults to kind semver with pattern *.

For container images the pattern is additionally narrowed per image, using the tag currently in the values file: an image on 0.37.0 is filtered with >=0.37.0, and a tagfilter regex derived from the shape of that tag is added so unrelated tag conventions are not considered.

More details on the "Version Filtering" page.

Manifest

Parameters

NameTypeDescriptionRequired
authsobject

auths provides a map of registry credentials where the key is the registry URL without scheme if empty, updatecli relies on OCI credentials such as the one used by Docker.

example:

auths:
  "ghcr.io":
    token: "xxx"
  "index.docker.io":
    username: "admin"
    password: "password"
    passwordstring

password specifies the container registry password to use for authentication. Not compatible with token

compatible: * source * condition * target

default: by default credentials are fetch from the local environment such as ~/.docker/config.json.

remark: Not compatible with token

    tokenstring

token specifies the container registry token to use for authentication.

compatible: * source * condition * target

default: by default credentials are fetch from the local environment such as ~/.docker/config.json.

remark: Not compatible with username/password

    usernamestring

username specifies the container registry username to use for authentication.

compatible: * source * condition * target

default: by default credentials are fetch from the local environment such as ~/.docker/config.json.

remark: Not compatible with token

digestbooleandigest provides a parameter to specify if the generated manifest should use a digest on top of the tag when updating container.
ignorearrayIgnore specifies rule to ignore Helm chart update.
    containersobjectContainers specifies a list of containers pattern.
    dependenciesobjectDependencies specifies a list of dependencies pattern.
    pathstringPath specifies a Helm chart path pattern, the pattern requires to match all of name, not just a subpart of the path.
ignorechartdependencybooleanignorechartdependency disables Helm chart dependencies update when set to true
ignorecontainerbooleanignorecontainer disables OCI container tag update when set to true
onlyarrayonly specify required rule(s) to restrict Helm chart update.
    containersobjectContainers specifies a list of containers pattern.
    dependenciesobjectDependencies specifies a list of dependencies pattern.
    pathstringPath specifies a Helm chart path pattern, the pattern requires to match all of name, not just a subpart of the path.
rootdirstringrootdir defines the root directory used to recursively search for Helm Chart
skippackagingboolean[target] Defines if a Chart should be packaged or not.
versionfilterobject

versionfilter provides parameters to specify the version pattern used when generating manifest.

kind - semver versionfilter of kind semver uses semantic versioning as version filtering pattern accepts one of: prerelease - Updatecli tries to identify the latest prerelease whatever it means patch - Updatecli only handles patch version update minor - Updatecli handles patch AND minor version update minoronly - Updatecli handles minor version only major - Updatecli handles patch, minor, AND major version update majoronly - Updatecli only handles major version update a version constraint such as >= 1.0.0

kind - regex versionfilter of kind regex uses regular expression as version filtering pattern accepts a valid regular expression

example:

  versionfilter:
    kind: semver
    pattern: minor

and its type like regex, semver, or just latest.

More examples can be found at https://www.updatecli.io/docs/core/versionfilter/

    kindstringspecifies the version kind such as semver, regex, or latest
    patternstringspecifies the version pattern according the version kind for semver, it is a semver constraint for regex, it is a regex pattern for time, it is a date format
    regexstringspecifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used.
    replaceallobjectreplaceAll applies a regex replacement to version strings before filtering. This is useful for transforming versions (e.g., curl-8_15_0 to curl-8.15.0) before regex extraction.
        patternstringPattern specifies the regex pattern to match for replacement
        replacementstringReplacement specifies the replacement string (supports $1, $2, etc. for captured groups)
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time
versionincrementstring[target] Defines if a Chart changes, triggers, or not, a Chart version update, accepted values is a comma separated list of none,major,minor,patch
⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli
Note
only and ignore rules accept path (a chart path pattern that must match the whole path), dependencies (a map of dependency name to version), and containers (a map of image name to tag).

Example

# updatecli.d/default.yaml
name: "Helm autodiscovery using git scm"
scms:
  epinio:
    kind: git
    spec:
      url: https://github.com/olblak/charts.git
      branch: master
    
autodiscovery:
  # scmid is applied to all crawlers
  scmid: epinio
  crawlers:
    helm:
      ignore:
        # Ignore a specific path:
        - path: charts/acme/*
        # Ignore a specific chart dependency:
        - dependencies:
            my-chart-dependency: ">0.0.1"
        # Ignore a specific image reference in chart values:
        - containers:
            "longhornio/upgrade-responder": ""
      
      # To include only a specific path:
      #only:
      #  - path: charts/*
Last updated on July 30, 2026
Prev
Golang
Next
Helmfile