Updatecli
Docs

Docker Digest

sourceconditiontarget

✔

✔

✗

Description

The dockerdigest resource resolves a container image tag to the digest it currently points at, so deployments can pin an immutable reference instead of a mutable tag.

source

Returns the digest for image and tag, in the form jenkins/jenkins:lts-jdk11@sha256:…​.

condition

Checks that an image exists in the registry for the given digest - digest when set, otherwise the source output. A missing image reports the Docker image <ref> doesn’t exist. rather than erroring.

target

Not supported - a target fails with Target not supported for the plugin Docker Digest. Write the digest into a file with the "Yaml" or "File" resources.

Note
An scm is accepted but ignored, logging scm is not supported, ignoring. The lookup always goes to the registry.

Parameters

NameTypeDescriptionRequired
architecturestring

“architecture” defines the platform of the container image, as “” or “/[/]”.

compatible:

  • source

remark:

  • when unset, the source returns the digest of the image as stored in the registry, which is the image index digest for a multi platform image.
  • when set, the source returns the digest of the image matching the platform.
  • the os defaults to “linux” when only the architecture is set.

example:

  • architecture: amd64
  • architecture: linux/arm64
  • architecture: linux/arm/v7
digeststring

“digest” defines the container image digest to check.

compatible:

  • condition

default: the output of the associated source.

remark:

  • it accepts “sha256:”, “@sha256:” or “@sha256:”.

example:

  • digest: sha256:ce782db15ab5491c6c6178da8431b3db66988ccd11512034946a9667846952a6
hidetagboolean

“hidetag” removes the tag from the source output.

compatible:

  • source

default: false

remark:

  • when false, the source returns “@sha256:”.
  • when true, the source returns “@sha256:”.
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.

compatible:

  • source

default: latest

remark:

  • a digest appended to the tag, as in “latest@sha256:…”, is ignored.

example:

  • tag: latest
  • tag: v0.1.0
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”.
image

Mandatory, e.g. updatecli/updatecli.

tag

Defaults to latest. It must not already contain a digest (a value starting with @ is rejected with invalid tag <image>: only contain a digest).

architecture

Defaults to amd64. Unset, the digest returned is that of the image index, valid on any platform; set, it is the digest of that one platform’s image. The two are different values for the same tag.

digest

Condition only, defaulting to the source output.

hidetag

Source only. Changes the shape of the returned value.

hidetag

By default the source keeps the tag alongside the digest, which stays readable in a diff while still pinning the exact image:

index.docker.io/jenkins/jenkins:lts-jdk11@sha256:ce782db15ab...

With hidetag: true the tag is dropped:

index.docker.io/jenkins/jenkins@sha256:ce782db15ab...

Authentication

Credentials are given inline on the spec. Depending on the registry, how you obtain a token differs.

Important
Storing credentials in an unencrypted manifest is a bad practice. Read them from the environment with '{{ requiredEnv "TOKEN" }}'.

GHCR

GitHub uses a personal access token (see Creating a personal access token).

DockerHub

The simplest route is to run docker login and read the token from ~/.docker/config.json:

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

Example

This example uses a Go template, updatecli.tpl, with values from values.yaml, so that {{ requiredEnv "…​" }} can read the GitHub token from the environment.

# updatecli.tpl
sources:
  lastDockerDigest:
    kind: dockerdigest
    spec:
      image: "jenkins/jenkins"
      tag: "lts-jdk11"
targets:
  imageTag:
    name: "jenkins/jenkins:lts-jdk11 docker digest"
    kind: yaml
    spec:
      file: "config/default/jenkins-release.yaml"
      key: "jenkins.master.imageTag"
    scm:
      github:
        user: "{{ .github.user }}"
        email: "{{ .github.email }}"
        owner: "jenkins-infra"
        repository: "charts"
        token: "{{ requiredEnv .github.token }}"
        username: "{{ .github.username }}"
        branch: "master"
# 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 digest of jenkins/jenkins:lts-jdk11 from DockerHub.

Target

Update the YAML key jenkins.master.imageTag in config/default/jenkins-release.yaml in the GitHub repository jenkins-infra/charts.

Links

Last updated on August 2, 2026
Prev
CSV
Next
Scm