Docker Image

source	condition	target
✔	✔	✗

Description

source

The Docker Image "source" retrieves a docker image tag from a Docker Registry

condition

The Docker Image "condition" tests if a docker image tag exist on a Docker Registry

Parameters

Name	Type	Description
architecture	string	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
architectures	array	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
image	string	image specifies the container image such as `updatecli/updatecli` compatible: condition source
password	string	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
tag	string	tag specifies the container image tag such as `latest` compatible: condition default: latest
tagfilter	string	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
token	string	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
username	string	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
versionfilter	object	versionfilter provides parameters to specify version pattern and its type like regex, semver, or just latest. compatible: source default: kind: latest
kind	string	specifies the version kind such as semver, regex, or latest
pattern	string	specifies 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
regex	string	specifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used.
replaceall	object	replaceAll 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.
strict	boolean	strict 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

When the parameter architecture or architectures the registry will be checked to see if they are present.

Remarks:

The default operating system is linux.
When query variant v7 for arm the operating system must also be defined.
Checking architectures is not supported for v1 registries

Here are some examples:

amd64 - will check for 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