Core on

Configuration

Tue, 13 Oct 2020 15:21:01 +0200

Updatecli requires a configuration file, or "manifest", which describes the update pipeline. A manifest describes the "what", the "when", and the "where" of the update pipeline.

Source

Sat, 09 Jan 2021 15:21:01 +0200

Description

The "source" stage retrieves information from a third "resource" like a file, or an API and then uses that information in later stages.

A source is the only stage that never modifies anything: it just reads a value, optionally reshapes it with transformers, and hands it over to the conditions and targets of the manifest.

Most sources return a list of candidate versions and pick one according to their versionfilter. See version filter for the available strategies.

Tip

Within a single Updatecli run, sources sharing the same kind, spec, and resolved repository are executed only once, and the result is reused. Naming them differently, or attaching different transformers, does not trigger a second call (which keeps API rate limits under control when many pipelines track the same dependency).

Condition

Sat, 09 Jan 2021 15:21:01 +0200

Description

A "condition" stage defines whether to run the "Target" stage stage of a pipeline. It runs a check (depending on the resource kind) that returns a boolean indicating its success (true) or failure (false).

Please look at each kind of resource (shell, file, etc.) for details about "how is the success/failure determined?".

By default, every target of a manifest waits for every condition to succeed. A single failing condition is enough to skip all the targets. That default can be changed per target, see Scoping conditions to specific targets.

Target

Sat, 09 Jan 2021 15:21:01 +0200

Description

The "target" stage applies the value retrieved by a source to a "resource", such as a file in a Git repository. It is the only stage allowed to modify something, and it runs only once every condition succeeded.

A target reports one of three outcomes:

success - the resource already holds the expected value, nothing to do
attention - the resource is out of date. In diff mode Updatecli only reports the change, in apply mode it writes it
failure - the target could not be evaluated

When a target is attached to an scmid, applying a change also commits it and pushes it to the configured branch, which in turn triggers the actions depending on that scm.

Action

Fri, 11 Apr 2025 15:21:01 +0200

Description

An Updatecli action defines what happens after a change is detected and validated. While Updatecli’s sources find changes (like a new version), and targets define where to apply them (like a file), actions describe what to do next, such as creating a pull request.

An action is bound to an scm through its scmid, and runs when a target using that same scm pushed a change. Targets working on the local directory, or on another scm, do not trigger it.

An action is only carried out in apply mode with push enabled. updatecli pipeline diff, and updatecli pipeline apply --push=false, describe the action that would be taken, including its title and body, without contacting the forge.

Note	When none of the related targets changed, Updatecli does not simply skip the action: it still looks for a pull request opened by a previous run, so that an update which became obsolete is reported rather than left dangling.

Scm

Sat, 09 Jan 2021 15:21:01 +0200

Description

An scm configuration provides the git repository information used by a source, a condition, a target, an action, or autodiscovery.

When an updatecli pipeline is triggered, the first thing updatecli does, is clone all referenced git repositories into a temporary directory. Resources referencing that scm through their scmid key then operate on the clone rather than on the current working directory, and a target that changes a file there gets its change committed and pushed to a branch named after the pipeline pipelineid.

A resource without an scmid simply works on the current working directory, and Updatecli neither clones nor commits anything for it. A manifest can ask for its own directory to be used instead, with options.relativepaths.

The `local` scm

local is a reserved scm identifier. Referencing scmid: local from a resource or an action, without declaring scms.local yourself, asks Updatecli to auto-detect the git repository of the current directory: its root, its remote, and its branch. This is how you commit changes to the repository you are already in, rather than to a clone.

Declaring scms.local explicitly overrides that detection, and setting disabled: true on it opts out of the auto-detection entirely.

targets:
 version:
 kind: file
 # Commit the change to the repository Updatecli runs in
 scmid: local
 spec:
 file: VERSION

Transformer

Sat, 09 Jan 2021 15:21:01 +0200

Description

The "transformers" parameter can be used by any stage definition as a "source", "condition", or "target". A "transformers" object contains a list of transformers. Each kind of transformer rules applies a string manipulation like adding or removing characters.

source

Source returns information modified by a list of transformers.

condition

A condition receives information from the source then modifies that value using transformers before using it in the resource.

target

A target receives information from the source then modifies that value with the transformers rule before using the resource.

Version Filter

Mon, 01 Jan 0001 00:00:00 +0000

Description

Most sources do not return a single value: a Docker registry returns every tag of an image, a GitHub repository every release, a package registry every published version. The versionfilter key decides which one of them the source actually returns.

Two things happen, depending on the kind:

sorting - semver, regex/semver, time, regex/time, pep440, and lex order the versions themselves, so the highest or most recent one wins whatever order the resource used.
filtering - pattern restricts the candidates, for instance to a major version, a release branch, or a date format.

latest and regex only filter: they keep the order given by the resource, which is usually the publication order.

The filter runs before the transformers, so transformers reshape the version that the filter selected, and never influence the selection itself.

Kinds

versionFilter allows to specify the kind of version retrieved from a resource and its version pattern. Default value is "latest" as we want to retrieve the newest version from a resource.

A version filter accepts the following keys:

Name Default Description

Name	Default	Description
`kind`	`latest`	One of `latest`, `lex`, `regex`, `semver`, `regex/semver`, `time`, `regex/time`, `pep440`. An unsupported value stops the run with an error.
`pattern`	depends on `kind`	The constraint applied to the versions, interpreted according to `kind`. Defaults to `.` for `regex`, for `semver` and `pep440`, and `2006-01-02` for `time` and `regex/time`.
`regex`	-	Used by `regex/semver` and `regex/time` only, to extract the version from a longer string. The first capture group is the value being filtered.
`replaceall`	-	An optional find-and-replace applied to each version before the filter, with the sub-keys `pattern` (a regular expression) and `replacement` (which may reference capture groups with `$1`, `$2`, …).
`strict`	`false`	Used by `semver` and `regex/semver` only. When `true`, only strictly formatted `MAJOR.MINOR.PATCH` versions are considered, so a lenient version such as `1.2` is dropped instead of being read as `1.2.0`.

kind

latest

One of latest, lex, regex, semver, regex/semver, time, regex/time, pep440. An unsupported value stops the run with an error.

pattern

depends on kind

The constraint applied to the versions, interpreted according to kind. Defaults to . for regex, for semver and pep440, and 2006-01-02 for time and regex/time.

regex

Used by regex/semver and regex/time only, to extract the version from a longer string. The first capture group is the value being filtered.

replaceall

An optional find-and-replace applied to each version before the filter, with the sub-keys pattern (a regular expression) and replacement (which may reference capture groups with $1, $2, …).

strict

false

Used by semver and regex/semver only. When true, only strictly formatted MAJOR.MINOR.PATCH versions are considered, so a lenient version such as 1.2 is dropped instead of being read as 1.2.0.

Note	Versions that cannot be parsed for the selected kind are silently skipped, not treated as errors. When nothing is left after filtering, the resource fails with "no version found".

latest

If kind is set to latest then there is no need to specify a pattern, as Updatecli returns the last version provided by the resource, in the order the resource returned them.

Important

latest does not compare versions, it trusts the ordering of the resource. For a Docker registry, that is the most recently pushed tag, which is not necessarily the highest version number. Use semver when you need the highest version.

Example

sources:
 kubectl:
 kind: githubRelease
 spec:
 owner: "kubernetes"
 repository: "kubectl"
 token: "{{ requiredEnv .github.token }}"
 username: "john"
 versionFilter:
 kind: latest
 transformers:
 - trimPrefix: "kubernetes-"

Return the latest Github release and remove "kubernetes-" from it.

Lex

If the kind is set to lex then Updatecli returns the latest version sorted lexicographically.

Sorting versions lexicographically means arranging them based on their lexicographic order, which is essentially alphabetical order as used in dictionaries, but applied to version strings.

For example, in lexicographic order:

"1.10" comes before "1.2", because it compares character by character:
 Compare "1" vs. "1" → equal.
 Compare "." vs "." → equal.
 Compare "1" vs. "2" → "1" is smaller, so "1.10" < "1.2".

This ordering does not account for numerical values of version components. For meaningful version comparisons, semantic versioning is typically preferred, where "1.2" < "1.10" because "2" is numerically smaller than "10".

Example

sources:
 ubuntu-focal:
 name: Get latest ubuntu focal docker image tag using regex/time versionfilter
 kind: dockerimage
 spec:
 image: ubuntu
 versionfilter:
 kind: lex

regex

If versionFilter.kind is set to regex then we can use versionFilter.pattern to specify a regular expression to return the newest version returned from a resource matching the regex If no versionFilter.pattern is provided then it uses '.*' which return the newest version

Note	Like `latest`, `regex` walks the versions in the order the resource returned them and stops on the first match, starting from the end. It filters, it does not sort. To compare version numbers, use `regex/semver`.

versionFilter.replaceall can optionally be used to transform version strings before the regex is applied. It accepts a pattern (regex) and a replacement string, similar to a find-and-replace operation.

sources:
 kubectl:
 kind: githubRelease
 spec:
 owner: "kubernetes"
 repository: "kubectl"
 token: "{{ requiredEnv .github.token }}"
 username: "john"
 versionFilter:
 kind: regex
 pattern: "kubernetes-1.(\\d*).(\\d*)$"
 transformers:
 - trimPrefix: "kubernetes-"

⇒ Return the newest kubectl version matching pattern "kubernetes-1.(\\d*).(\\d*)$" and remove "kubernetes-" from it

Example with replaceall

Some projects use version tags that are not directly compatible with the regex pattern. For example, curl uses tags like curl-8_11_1 where underscores separate version components. The replaceall option can be used to normalize these tags before applying the regex.

sources:
 curl:
 kind: githubRelease
 spec:
 owner: "curl"
 repository: "curl"
 versionFilter:
 kind: regex
 pattern: 'curl-\d+\.\d+\.\d+'
 replaceall:
 pattern: "_"
 replacement: "."

⇒ The replaceall converts curl-8_11_1 to curl-8.11.1, and the newest tag matching pattern is returned as curl-8.11.1

Important

With kind: regex, the returned value is the whole transformed version, not a capture group - the regex key is ignored, only pattern is read. Use kind: regex/semver when you need to extract 8.11.1 out of curl-8.11.1, and add a trimprefix transformer otherwise.

semver

If versionFilter.kind is set to semver then we can use versionFilter.pattern to specify version pattern as explained here. In the process we also sort. If no versionFilter.pattern is provided then it falls back to '*' which returns the newest version. Versions that do not respect semantic versioning are ignored.

Setting versionFilter.strict to true additionally rejects versions that are only loosely semantic, such as 1.2 or v1, instead of completing them with zeros.

Remark

In the process we drop any characters not respecting semantic version like in this version "v1.0.0", we drop the "v" but we can add it back using transformers.

Autodiscovery patterns

On top of the standard constraints, semver accepts the following keywords, which are resolved against the version currently in use. They are what the autodiscovery crawlers use to restrict the scope of an update.

Pattern Meaning

Pattern	Meaning
`patch`	Only patch updates, keeping the same major and minor.
`minor`	Minor and patch updates, keeping the same major.
`minoronly`	Minor updates only, excluding patch updates within the current minor.
`major`	Any update from the current major upwards.
`majoronly`	Major updates only.
`prerelease`	Pre-releases of the current version.

patch

Only patch updates, keeping the same major and minor.

minor

Minor and patch updates, keeping the same major.

minoronly

Minor updates only, excluding patch updates within the current minor.

major

Any update from the current major upwards.

majoronly

Major updates only.

prerelease

Pre-releases of the current version.

Example

 jenkins-wiki-exporter:
 kind: githubRelease
 spec:
 owner: "jenkins-infra"
 repository: "jenkins-wiki-exporter"
 token: "{{ requiredEnv .github.token }}"
 username: "john"
 versionFilter:
 kind: semver
 pattern: "~1.10"

⇒ Return the version "v1.10.3"

regex/semver

If versionFilter.kind is set to regex/semver then we can use versionFilter.regex to specify a regular expression to extract version numbers. The regular expression should return the semantic version in the first capturing group. We can then use versionFilter.pattern to specify version pattern as explained here. In the process we also sort. If no versionFilter.pattern is provided then it falls back to '*' which returns the newest version. Extracted values that do not respect semantic versioning are ignored.

Important

The regular expression must define at least one capture group; a version without one is skipped. pattern filters the extracted value, regex extracts it (the two are not interchangeable).

Example

sources:
 default:
 name: Get latest version
 kind: githubrelease
 spec:
 owner: yarnpkg
 repository: berry
 token: '{{ requiredEnv "GITHUB_TOKEN" }}'
 versionfilter:
 kind: regex/semver
 regex: "@yarnpkg/cli/(\\d*\\.\\d*\\.\\d*)"

⇒ Return the version "4.5.3"

regex/time

If versionFilter.kind is set to regex/time then we can use versionFilter.regex to specify a regular expression to extract dates. The regular expression should return the date in the first capturing group. We can then use versionFilter.pattern to specify date pattern as explained here. In the process we also sort. If no versionFilter.pattern is provided then it falls back to '2006-01-02' which returns the newest version using date format YYYY-MM-DD. Extracted values that do not match the date pattern are ignored.

To define your own format/pattern, write down what the reference time would look like formatted your way; The model is to demonstrate what the reference time looks like so that the Format and Parse methods can apply the same transformation to a general time value.

Here is a summary of the components of a layout string. Each element shows by example the formatting of an element of the reference time. Only these values are recognized. Text in the layout string that is not recognized as part of the reference time is echoed verbatim during Format and expected to appear verbatim in the input to Parse.

Year: "2006" "06"
Month: "Jan" "January" "01" "1"
Day of the week: "Mon" "Monday"
Day of the month: "2" "_2" "02"
Day of the year: "__2" "002"
Hour: "15" "3" "03" (PM or AM)
Minute: "4" "04"
Second: "5" "05"
AM/PM mark: "PM"

You can get inspiration from the following examples

Pattern

Example

2006-01-02

2021-01-02 (YYYY-MM-DD)

20060102

20210102 (YYYYMMDD)

20060201

20260201 (YYYYDDMM)

Example

sources:
 ubuntu-focal:
 name: Get latest ubuntu focal docker image tag using regex/time versionfilter
 kind: dockerimage
 spec:
 image: ubuntu
 versionfilter:
 kind: 'regex/time'
 regex: '^focal-(\d*)$'
 pattern: "20060102"

time

If versionFilter.kind is set to time then we can use versionFilter.pattern to specify date pattern as explained here. In the process we also sort. If no versionFilter.pattern is provided then it fallback to '2006-01-02' which return the newest version using date format YYYY-MM-DD. Please note date time not matching the pattern will be ignored.

Year: "2006" "06"
Month: "Jan" "January" "01" "1"
Day of the week: "Mon" "Monday"
Day of the month: "2" "_2" "02"
Day of the year: "__2" "002"
Hour: "15" "3" "03" (PM or AM)
Minute: "4" "04"
Second: "5" "05"
AM/PM mark: "PM"

You can get inspiration from the following examples

Pattern

Example

2006-01-02

2021-01-02 (YYYY-MM-DD)

20060102

20210102 (YYYYMMDD)

20060201

20260201 (YYYYDDMM)

Example

sources:
 ubuntu:
 name: Get latest ubuntu docker image tag using time versionfilter
 kind: dockerimage
 spec:
 image: ubuntu
 versionfilter:
 kind: 'time'
 pattern: "06.01"

pep440

If versionFilter.kind is set to pep440 then versions are parsed and sorted according to the Python PEP 440 specification, and versionFilter.pattern is a PEP 440 specifier such as >=1.0,<2.0. Versions that are not valid PEP 440 versions are ignored.

This is the right choice for Python packages, whose versions are not semantic versions: PEP 440 understands epochs (1!2.0), post-releases (1.0.post1), development releases (1.0.dev1), and pre-release spellings such as 1.0rc1 or 1.0a1, which semver rejects or misorders.

If no versionFilter.pattern is provided then it falls back to *.

Important

With *, or with no pattern at all, Updatecli returns the newest stable version and only falls back to a pre-release when no stable version exists. An explicit specifier does not apply that preference: it returns the newest version satisfying it, pre-release or not.

Example

sources:
 ansible:
 name: Get the latest stable Ansible release
 kind: pypi
 spec:
 name: ansible
 versionfilter:
 kind: pep440

Manifest Order

Wed, 15 Apr 2026 07:21:01 +0200

Description

Updatecli orders execution at two different levels:

between manifests, with the root keys id and dependson, described on this page
between the resources of one manifest, with the resource key dependson, described in Resource ordering

The two are independent: dependson at the root of a manifest refers to other manifests, while dependson inside a source, condition, or target refers to other resources of the same manifest.

Labels

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Pipeline labels are arbitrary key/value pairs attached to a pipeline manifest that allow you to categorize, organize, and filter pipelines during execution and reporting.

updatecli.yaml

name: "docs: update Golang version throughout the documentation"

# Pipeline labels: key/value pairs used to filter and organize pipelines in Updatecli and Udash.
labels:
 ecosystem: go

actions:
 default:
 kind: github/pullrequest
 spec:
 # PR labels: applied to the pull request on the SCM (e.g. GitHub). Different from pipeline labels above.
 labels:
 - dependencies

These labels can be used for two main purposes:

Filtering pipeline execution - Use labels to run only specific pipelines matching given criteria.

For example, only apply pipelines tagged with ecosystem: go:
```
updatecli compose apply --labels="ecosystem:go"
```
Pipelines matching the filter will execute. Pipelines without the label or with a different value will be skipped.
Filtering pipeline reports in Udash, where labels group pipelines from many repositories into one view. See Filtering by label.

Core on

Configuration

Source

Description

Condition

Description

Target

Description

Action

Description

Scm

Description

The local scm

Transformer

Description

Version Filter

Description

Kinds

latest

Example

Lex

Example

regex

Example with replaceall

semver

Autodiscovery patterns

Example

regex/semver

Example

regex/time

Example

time

Example

pep440

Example

Manifest Order

Description

Labels

Overview

The `local` scm