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 specifies the container image architecture such as amd64

compatible:

  • condition
  • source

example: windows/amd64, linux/arm64, linux/arm64/v8

default: linux/amd64

remark: If an architecture is undefined, Updatecli retrieves the digest of the image index which can be used regardless of the architecture. But if an architecture is specified then Updatecli retrieves a specific image digest. More information on https://github.com/updatecli/updatecli/issues/1603

architecturesarray

architectures specifies a list of architectures to check container images for (conditions only)

compatible:

  • condition
  • source

example: windows/amd64, linux/arm64, linux/arm64/v8

default: linux/amd64

remark: If an architecture is undefined, Updatecli retrieves the digest of the image index which can be used regardless of the architecture. But if an architecture is specified then Updatecli retrieves a specific image digest. More information on https://github.com/updatecli/updatecli/issues/1603

imagestring

image specifies the container image such as updatecli/updatecli

compatible:

  • condition
  • source
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

tagstring

tag specifies the container image tag such as latest

compatible:

  • condition

default: latest

tagfilterstring

tagfilter allows to restrict tags retrieved from a remote registry by using a regular expression.

compatible:

  • source

example: ^v\d*(.\d*){2}-alpine$

default: none

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

versionfilterobject

versionfilter provides parameters to specify version pattern and its type like regex, semver, or just latest.

compatible:

  • source

default: kind: latest

    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.
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time

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 July 30, 2026
Prev
Transformer
Next
Dockerfile