Docs

Dockerfile

Description

The Dockerfile crawler looks recursively for all Dockerfile from a specific root directory. Then, for each of them, it tries to update each Docker image tag found in a 'FROM' instruction.

Updatecli looks for the following file patterns:

  • Dockerfile

  • Dockerfile.*

Override them with the filematch parameter.

The automatic discovery behavior can be tuned by providing a YAML manifest with a dockerfile crawler in top-level directive autodiscovery as explained in the "Autodiscovery" page.

Usage

The dockerfile autodiscovery can use with or without manifest.

Without manifest

Without manifest available, Updatecli will enable all default crawlers, including dockerfile.

updatecli diff to run updatecli in dryrun updatecli apply to apply the changes locally

With a manifest

If a manifest is provided, Updatecli will only execute crawlers specified in the manifest such as in the following example

  • updatecli diff --config updatecli.d/default.yaml to run updatecli in dryrun

  • updatecli apply --config updatecli.d/default.yaml to apply the changes

# updatecli.d/default.yaml
name: "[asciidoctor/docker-asciidoctor] Dockerfile autodiscovery using git scm"
scms:
  asciidoctor:
    kind: git
    spec:
      url: https://github.com/asciidoctor/docker-asciidoctor.git
      branch: main

autodiscovery:
  # scmid is applied to all crawlers
  scmid: asciidoctor
  crawlers:
    dockerfile:
      #rootdir: <custom root directory, overriden by scm configuration>
      #
      ## Ignore Dockerfile update matching following rules
      #ignore:
      #  - archs:
      #      - "amd64"
      #    path: "qa/*"
      #    images:
      #      - alpine
      #      - alpine:3
      #  
      ## Only update Dockerfile matching following rules
      #only:
      #  - archs:
      #      - "amd64"
      #    path: "qa/*"
      #    images:
      #      - alpine
      #      - alpine:3
      #
      # auths:
      # Override default dockerfile filematch
      #filematch:
      #  - "Dockerfile.example"

Generated manifests

Each image produces a dockerimage source for the latest tag and a dockerfile target that rewrites the instruction in place. When digest pinning is enabled, a dockerdigest source is added and the digest is written alongside the tag.

digest defaults to true. Set digest: false to track the tag only.

Three details of how FROM instructions are read:

  • Build arguments are followed. For ARG GOVERSION=1.21 used as FROM golang:${GOVERSION}, the target writes to the ARG instruction rather than the FROM line, so the default stays authoritative.

  • Stage aliases are skipped. A FROM builder AS final referring to an earlier stage is not an external image and yields no manifest.

  • Flags are ignored. FROM --platform=linux/amd64 alpine:3.18 is handled normally.

Authentication

Use auths to reach private registries, keyed by registry URL without a scheme, accepting either a token or a username/password pair. When it is empty Updatecli falls back to the ambient OCI credentials, such as those written by docker login.

Manifest

Parameters

NameTypeDescriptionRequired
authsobject

“auths” defines the registry credentials, keyed by registry host without scheme.

remark:

  • when empty, Updatecli uses the local OCI credentials, such as the Docker ones.

example:

auths:
  "ghcr.io":
    token: "xxx"
  "index.docker.io":
    username: "admin"
    password: "password"
    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”.
    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”.
digestboolean

“digest” defines whether the generated manifests pin the image digest in addition to the tag.

default: true

filematcharray

“filematch” defines the file name patterns used to identify Dockerfiles.

default:

filematch:
  - "Dockerfile"
  - "Dockerfile.*"

remark:

  • the pattern is matched against the file name only, not against its path.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
ignorearray

“ignore” defines rules to exclude matching container images from the autodiscovery.

remark:

  • a container image is ignored when it matches at least one rule.
    archsarray

“archs” defines the image architectures to match.

remark:

  • an architecture must be identical to one of the entries.
  • the architecture is the value of the “–platform” flag of a “FROM” instruction, such as “linux/amd64”.
    imagesarray

“images” defines the container images to match.

remark:

  • an image name, without its tag, must be identical to one of the entries.
    pathstring

“path” defines a Dockerfile path pattern.

remark:

  • the pattern must match the whole path, not just a substring.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
onlyarray

“only” defines rules to restrict the autodiscovery to matching container images.

remark:

  • a container image is kept only when it matches at least one rule.
    archsarray

“archs” defines the image architectures to match.

remark:

  • an architecture must be identical to one of the entries.
  • the architecture is the value of the “–platform” flag of a “FROM” instruction, such as “linux/amd64”.
    imagesarray

“images” defines the container images to match.

remark:

  • an image name, without its tag, must be identical to one of the entries.
    pathstring

“path” defines a Dockerfile path pattern.

remark:

  • the pattern must match the whole path, not just a substring.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
rootdirstring

“rootdir” defines the directory where the crawler starts searching for Dockerfiles.

default: the scm directory when “scmid” is set, otherwise the directory relative paths resolve from, by default the working directory.

remark:

  • a relative path is resolved from the default directory.
  • an absolute path is used as is, instead of the scm directory.
versionfilterobject

“versionfilter” defines the version filter used by the generated manifests.

default: kind “semver” with pattern “>=”, combined with a tag filter derived from the current tag.

remark:

  • with kind “semver”, “pattern” accepts:
    • “prerelease”: the latest prerelease of the current version.
    • “patch”: patch updates only.
    • “minor”: patch and minor updates.
    • “minoronly”: minor updates only.
    • “major”: patch, minor and major updates.
    • “majoronly”: major updates only.
    • a version constraint, such as “>= 1.0.0”.
  • with kind “regex”, “pattern” accepts a regular expression.
  • more examples at https://www.updatecli.io/docs/core/versionfilter/

example:

versionfilter:
  kind: semver
  pattern: minor
    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”.

        patternstring

“pattern” defines the regular expression matching the text to replace.

example:

  • pattern: “_”
        replacementstring

“replacement” defines the text replacing each match of “pattern”.

remark:

  • capture groups can be referenced with $1, $2, and so on.

example:

  • replacement: “.”
    strictboolean

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

default: false

remark:

  • only used by the kinds “semver” and “regex/semver”.
⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli

Docker Image Tag

The Docker ecosystem has no versioning guidelines. This means that it’s the wild west out there and pretty much impossible to detect all cases. Hence why Updatecli manifest was created.

That being said we are still interested in an autodiscovery feature that would detect as many cases as possible. This section is about documentation what is covered and what’s missing. Do not hesitate to look at the contributing section

Semantic Versioning

In the Docker ecosystem, many tags look like semver but are not. For instance, node:18.12.1-alpine would match the semver regular expression but the prerelease -alpine is not a prerelease information as per semver convention but a variant of node:18.12.1-buster or node:18.12.1. This means that we would expect a newer version with the -alpine such as node:19.0.0-alpine.

The dockerfile autodiscovery will handle the following scenarios

  • 1 will suggest a version such 2 otherwise stick to 1

  • 1-alpine will suggest a version such 2-alpine otherwise stick to 1-alpine

  • 1.0 will suggest a version such 2.1 otherwise stick to 1.0

  • 1.0-alpine will suggest a version such 2.1-alpine otherwise stick to 1.0-alpine

  • 1.0.0 will suggest a version such 2.1.0 otherwise stick to 1.0.0

  • 1.0.0-alpine will suggest a version such 2.1.0-alpine otherwise stick to 1.0.0-alpine

Any other version pattern such as PEP 440 are ignored in the current state. We are planning to add new versionFilter kinds in the future as the need raise.

Feel free to:

  1. Open an issue explaining the version pattern you are looking for.

  2. Add a +1 to an existing issue as it helps us to prioritise

  3. Contribute to an existing one as it will move things faster.

Last updated on August 2, 2026
Prev
Docker Compose
Next
Flux