Docs

Docker Image

sourceconditiontarget

✔

✔

✗

Description

The dockerimage resource queries a container registry about an image.

source

Returns the image tag matching versionfilter.

condition

Tests that a tag exists for the image, optionally for a set of architectures.

target

Not supported - a target fails with target not supported for the plugin Docker Image. To write a tag into a file, use the "Yaml" or "Dockerfile" resources.

Note
An scm attached to a condition is ignored, with a warning (the lookup always goes to the registry).

To pin an image by digest rather than by tag, see the "Docker Digest" resource.

Parameters

NameTypeDescriptionRequired
architecturestring

“architecture” defines the platform the container image must exist for.

compatible:

  • source
  • condition

remark:

  • “architecture” and “architectures” are mutually exclusive.
  • a platform is written “” or “/[/]”. The os defaults to “linux”.
  • when unset, Updatecli checks the image index, which applies to every platform. When set, Updatecli checks the image for that specific platform. More information on https://github.com/updatecli/updatecli/issues/1603

example:

  • architecture: amd64
  • architecture: windows/amd64
  • architecture: linux/arm64/v8
architecturesarray

“architectures” defines the list of platforms the container image must exist for.

compatible:

  • source
  • condition

remark:

  • “architecture” and “architectures” are mutually exclusive.
  • a platform is written “” or “/[/]”. The os defaults to “linux”.
  • a source only checks the first platform of the list.
  • a condition checks every platform of the list.
  • when unset, Updatecli checks the image index, which applies to every platform. When set, Updatecli checks the image for that specific platform. More information on https://github.com/updatecli/updatecli/issues/1603

example:

  architectures:
    - windows/amd64
    - linux/arm64
    - linux/arm64/v8
imagestring

“image” defines the container image name.

compatible:

  • source
  • condition

example:

  • image: updatecli/updatecli
  • image: ghcr.io/updatecli/updatecli
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”.
tagstring

“tag” defines the container image tag to check.

compatible:

  • condition

default: the output of the associated source.

example:

  • tag: latest
  • tag: v0.1.0
tagfilterstring

“tagfilter” defines a regular expression restricting the tags retrieved from the registry.

compatible:

  • source

remark:

  • it is applied before “versionfilter”.

example:

  • tagfilter: ^v\d*(.\d*){2}-alpine$
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”.
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”.
versionfilterobject

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

compatible:

  • source

default: kind: latest

    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”.

Remark:

It’s considered a very bad practice to store credentials in an unencrypted file. Consider using an environment variable to store the token.

Architectures

architecture names one platform; architectures takes a list, and the condition passes only when the tag exists for all of them.

Important

Leaving both unset is not the same as asking for the default platform. With no architecture, Updatecli retrieves the digest of the image index - the multi-architecture manifest list, valid whichever platform pulls it. Naming an architecture retrieves the digest of that specific image instead.

The two digests are different values for the same tag, so switching between them changes what a source returns. See updatecli#1603.

Remarks:

  • The default operating system is linux, so amd64 means linux/amd64.

  • When querying the v7 variant of arm, the operating system must be spelled out: linux/arm/v7.

  • Checking architectures is not supported on v1 registries.

Accepted forms:

  • amd64 - checks linux/amd64

  • linux/amd64

  • windows/amd64

  • linux/arm/v7

Authentication

Depending on the Docker Registry, authentication may be required. The way to retrieve the token depends on the registry.

GHCR

Github uses personal access token. How to retrieve one, is explained here

DockerHub

To retrieve the token, it’s easier to run docker login and then retrieve the token stored in '~/.docker/config.json'

~/.docker/config.json
        "auths": {
                "https://index.docker.io/v1/": {
                        "auth": "token"
                }
        },

Example

Please note that in this example we are using a go template updatecli.tpl with values from values.yaml The main motivation is to use {{ requiredEnv ENV_VARIABLE }} to read the github token from a environment variable.

# updatecli.yaml
name: Docker Image

sources:
  lastGithubRelease:
    kind: githubrelease
    spec:
      owner: "jenkins-infra"
      repository: "plugin-site-api"
      token: "{{ requiredEnv .github.token }}"
      username: "olblak"
      versionfilter:
        kind: latest

conditions:
  docker:
    name: "Docker Image Published on Registry"
    kind: dockerimage
    spec:
      image: "jenkinsciinfra/plugin-site-api"
      architecture: "linux/amd64"

targets:
  imageTag:
    name: "jenkinsciinfra/plugin-site-api docker image"
    kind: yaml
    spec:
      file: "charts/plugin-site/values.yaml"
      key: "$.backend.image.tag"
    scmid: default


scms:
  default:
    kind: github
    spec:
      user: "{{ .github.user }}"
      email: "{{ .github.email }}"
      owner: "{{ .github.owner }}"
      repository: "{{ .github.repository }}"
      token: "{{ requiredEnv .github.token }}"
      username: "{{ .github.username }}"
      branch: "{{ .github.branch }}"
    disabled: false

# values.yaml
github:
  user: "updatebot"
  email: "updatebot@olblak.com"
  username: "jenkins-infra-bot"
  token: "UPDATECLI_GITHUB_TOKEN"
  branch: "master"
  owner: "olblak"
  repository: "charts"

What it says:

Source Retrieve the latest version from the Github release of the project jenkis-infra/plugins-site-api ⇒ v1.11.1

Condition Test that the tag v1.11.1 exist for the image jenkinsciinfra/plugin-site-api on DockerHub and architecture linux/amd64 is present ⇒ No, then abort

target If the condition was passing then it would have update the key backend.image.tag in the yaml file charts/plugin-site/values.yaml located on the Github repository olblak/charts on the branch master using the Github Pull request workflow

Last updated on August 2, 2026
Prev
Transformer
Next
Dockerfile