Updatecli
Docs

Helm Chart

sourceconditiontarget

✔

✔

✔

Description

The helmchart resource works at two levels, and which one applies depends on the stage:

source and condition

Talk to a chart repository. The source returns the latest version of a published chart; the condition checks that version exists there.

target

Works on a chart in your repository. It updates a value in the chart’s values.yaml, then maintains the chart’s own metadata (bumping version, optionally appVersion, and refreshing requirements.lock).

That asymmetry is the thing to keep in mind: url addresses the remote repository and is read-only, while name and key address the local chart the target rewrites.

Parameters

NameTypeDescriptionRequired
appversionboolean

“appversion” defines whether the chart “appVersion” is updated.

compatible:

  • target

default: false

remark:

  • the value is retrieved from the source output.
  • the “appVersion” field is only updated when the chart metadata already holds it.
filestring

“file” defines the chart file to update.

compatible:

  • target

default: values.yaml

remark:

  • the path is relative to the chart root directory.
  • the chart directory is defined by “name”.
keystring

“key” defines the yamlpath query used to retrieve the value from the yaml file.

compatible:

  • target

remark:

  • “key” is required in a target.
  • “key” is a simpler version of yamlpath.

example:

  • key: $.image.tag
  • key: $.images[0].tag
namestring

“name” defines the chart name, or the chart path such as “stable/chart”.

compatible:

  • source
  • condition
  • target

remark:

  • in a target, “name” is the chart directory path. When used with an scm, it is relative to the scm repository root directory, such as “stable/chart”.

example:

  • name: stable/chart
passwordstring

“password” defines the container registry password used for authentication.

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

remark:

  • “password” requires “username”.
  • “token” cannot be combined with both “username” and “password”.
skippackagingboolean

“skippackaging” defines whether the chart dependencies update is skipped.

compatible:

  • target

default: false

tokenstring

“token” defines the container registry bearer token used for authentication.

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

remark:

  • “token” cannot be combined with both “username” and “password”.
urlstring

“url” defines the chart repository location.

compatible:

  • source
  • condition

remark:

  • the schemes “https://”, “http://”, “oci://” and “file://” are supported.
  • a url without scheme is read as a local path.
  • “index.yaml” is appended when the url does not end with it.

example:

  • url: index.yaml
  • url: file://./index.yaml
  • url: https://github.com/updatecli/charts.git
  • url: oci://ghcr.io/olblak/charts/
usernamestring

“username” defines the container registry username used for authentication.

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

remark:

  • “username” requires “password”.
  • “token” cannot be combined with both “username” and “password”.
valuestring

“value” defines the value associated with the yamlpath query.

compatible:

  • target

default: the output of the associated source.

versionstring

“version” defines the chart version to check on the registry.

compatible:

  • condition

default: the output of the associated source.

versionfilterobject

“versionfilter” defines the version pattern and its kind, such as “regex”, “semver” or “latest”.

compatible:

  • source

default: semver

    kindstring

“kind” defines the versioning scheme used to select a version.

default: latest

remark:

  • accepted values are “latest”, “semver”, “regex”, “regex/semver”, “time”, “regex/time”, “lex” and “pep440”.
  • “latest” returns the last version of the list.
  • “lex” sorts the versions lexicographically and returns the last one.
  • “pep440” follows https://peps.python.org/pep-0440/

example:

  • kind: semver
    patternstring

“pattern” defines the version pattern, according to “kind”.

default:

  • latest: “latest”
  • semver and pep440: “*”
  • regex: “.*”
  • time and regex/time: “2006-01-02”

remark:

  • for “latest”, “latest” returns the last version, any other value must match a version exactly.
  • for “semver” and “regex/semver”, it is a semantic versioning constraint.
  • for “pep440”, it is a pep440 version specifier.
  • for “regex”, it is a regular expression.
  • for “time” and “regex/time”, it is a Go date layout.
  • ignored by “lex”.

example:

  • pattern: ~1.2
  • pattern: “>=1.0.0 <2.0.0”
  • pattern: ^v\d+.\d+.\d+$
    regexstring

“regex” defines the regular expression extracting the version from each entry.

remark:

  • only used by the kinds “regex/semver” and “regex/time”.
  • the value of the first capture group is used as the version.

example:

  • regex: ^v(\d+.\d+.\d+)$
    replaceallobject

“replaceall” applies a regular expression replacement to each version before filtering.

remark:

  • only used by the kinds “regex”, “regex/semver” and “regex/time”.
  • the replacement runs before “pattern” or “regex” is evaluated.

example:

replaceall:
  pattern: "_"
  replacement: "."

turns “curl-8_15_0” into “curl-8.15.0”.

    strictboolean

“strict” enforces strict semantic versioning rules when parsing versions.

default: false

remark:

  • only used by the kinds “semver” and “regex/semver”.
versionincrementstring

“versionincrement” defines how the chart version is bumped when the chart changes.

compatible:

  • target

default: minor

remark:

  • accepted values are a comma separated list of “major”, “minor” and “patch”, or one of “auto” or “none” on its own.
  • “none” disables the chart version update.
  • “auto” bumps the part of the chart version matching the part that changed in the updated value.
  • when several pipelines update the same chart, the increment is applied several times. More information on https://github.com/updatecli/updatecli/issues/693

example:

  • versionincrement: patch
  • versionincrement: major,minor
name

The chart, as stable/chart. With an scm, it is the path to the chart relative to the repository root.

file

Defaults to values.yaml, resolved relative to the chart root (not to the repository root).

key

Target only. The yamlpath of the value to update, e.g. $.image.tag.

url

Source and condition only. Accepts a repository index, a git URL, or an OCI registry:

index.yaml
file://./index.yaml
https://github.com/updatecli/charts.git
oci://ghcr.io/olblak/charts/
version

Condition only.

Credentials for an OCI registry are given inline on the spec, next to the other fields, rather than under a nested key.

Version bumping

versionincrement controls what happens to the chart’s own version when a target changes something. It defaults to minor, and accepts a comma-separated list of none, major, minor, patch and auto.

Warning

The increment is applied per target. When several targets in the same pipeline update the same chart, the chart version is bumped once for each of them - three targets with the default minor move a chart from 1.0.0 to 1.3.0. Use versionincrement: none on all but one of them, and see updatecli#693.

appversion: true also writes the source value into the chart’s appVersion field (the usual choice when the chart ships one application whose image tag you are bumping).

skippackaging: true updates the files without packaging the chart afterwards.

Version filtering

Unlike most resources, versionfilter defaults to semver here rather than to the generic filter, since charts are required to carry semantic versions. See the "Version Filtering" page.

Example

# updatecli.yaml
name: Example of Helm Chart resources

scms:
  default:
    kind: github
    spec:
      user: "john"
      email: "john@example.com"
      owner: "olblak"
      repository: "charts"
      token: "{{ requiredEnv .github.token }}"
      username: "john"
      branch: "master"

sources:
  lastRelease:
    kind: helmchart
    spec:
      url: https://charts.jenkins.io
      name: jenkins

conditions:
  isPrometheuseHelmChartVersionAvailable:
    name: "Test if the prometheus helm chart is available"
    kind: helmchart
    spec:
      url: https://prometheus-community.github.io/helm-charts
      name: prometheus
      version: "11.16.5"

targets:
  chartjenkins:
    name: Bump Jenkins Upstream Chart Version
    kind: helmchart
    spec:
      name: "charts/jenkins"
      file: "requirements.yaml"
      key: "dependencies[0].version"
      versionincrement: minor

What it says:

Source

Retrieve the version of the Jenkins chart from https://charts.jenkins.io (2.7.1).

Condition

Check that version 11.16.5 of the prometheus chart is available from https://prometheus-community.github.io/helm-charts. If not, the pipeline stops.

Target

Bump the upstream version into the local chart, drop requirements.lock if present, increment the chart version, then commit and open a pull request on GitHub.

Links

Last updated on August 2, 2026
Prev
HCL
Next
HTTP