Condition

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.

Parameters

Name	Type	Description	Required
dependson	array	“dependson” allows to specify the order of execution of resources. It accepts a list of rules like “(resourceType#)resourceId(:booleanOperator)”. The resourceType is optional and can be one of “condition”, “source” or “target” By default the resourceType is the current resource type The resourceId is the name of the resource to depend on The booleanOperator is optional and can be “AND” or “OR” examples: dependson: * condition#myCondition:and * source#mySource remarks: The parameters “sourceid” and “conditionsids” affect the order of resource execution. To avoid circular dependencies, the depended resource may need to remove any conditionids or set “disablesourceinput to true”.
disablesourceinput	boolean
failwhen	boolean
kind	string	kind specifies the conditions resource kind
name	string	name specifies the resource name
scmid	string	scmid specifies the scm configuration key associated to the current resource
sourceid	string
spec	object	spec specifies parameters for a specific conditions kind
transformers	array	transformers defines how the default input value need to be transformed
addprefix	string	“addprefix” defines a prefix added to the value. example: addprefix: v
addsuffix	string	“addsuffix” defines a suffix added to the value. example: addsuffix: -alpine
find	string	“find” defines a regular expression, and replaces the value with its first match. remark: when nothing matches, the value becomes empty. example: find: \d+.\d+.\d+
findsubmatch	object	“findsubmatch” defines a regular expression, and replaces the value with one of its capture groups. example: `findsubmatch: pattern: 'v(\d+)\.(\d+)' captureindex: 1`	[pattern]
jsonmatch	object	“jsonmatch” defines a query extracting a value from a json input. example: `jsonmatch: key: .version`	[key]
quote	boolean	“quote” wraps the value in double quotes. default: false remark: special characters in the value are escaped, following Go string syntax.
replacer	object	“replacer” defines a single replacement applied to the value. example: `replacer: from: "_" to: "."`	[from to]
replacers	array	“replacers” defines a list of replacements applied to the value. remark: all replacements run in a single pass, so a replaced text is never replaced again. example: `replacers: - from: "_" to: "." - from: "v" to: ""`
semverinc	string	“semverinc” defines a comma separated list of semantic version components to increment. remark: accepted components are “major”, “minor” and “patch”, applied in the order given. the value must be a valid semantic version. spaces around the commas are not accepted. example: semverinc: patch semverinc: minor,patch
trimprefix	string	“trimprefix” defines a prefix removed from the value. example: trimprefix: v
trimsuffix	string	“trimsuffix” defines a suffix removed from the value. example: trimsuffix: -alpine
unquote	boolean	“unquote” removes the double quotes around the value. default: false

Source input

Like a target, a condition receives the output of a source as its default input value:

when the manifest defines exactly one source, that source is used automatically
when the manifest defines more than one source, sourceid becomes mandatory
setting disablesourceinput: true runs the condition standalone, without any source value

Setting sourceid (or letting Updatecli guess it) also makes the condition wait for that source to run first.

Using `failwhen`

The failwhen parameter allows you to invert the result of a condition:

failwhen: false → Normal behavior: success is success, failure is failure. (Default behavior)
failwhen: true → Inverted behavior: success is treated as failure, failure is treated as success.

This is particularly useful for testing or enforcing negative checks.

Scoping conditions to specific targets

Because a target waits for all conditions by default, a manifest holding several unrelated targets and conditions may skip more than intended. To scope conditions, set disableconditions: true on the target and list only the relevant conditions with dependson, using the condition# prefix:

conditions:
  dockerImageExists:
    kind: dockerimage
    spec:
      image: updatecli/updatecli

  chartExists:
    kind: helmchart
    spec:
      url: https://updatecli.github.io/charts
      name: updatecli

targets:
  dockerfile:
    kind: dockerfile
    # Only "dockerImageExists" gates this target
    disableconditions: true
    dependson:
      - condition#dockerImageExists
    spec:
      file: Dockerfile
      instruction:
        keyword: FROM
        matcher: updatecli/updatecli

Important

The older conditionids target keyword is deprecated in favor of dependson with condition# keys, and cannot be combined with disableconditions.

Examples

Example with only 1 source:

sources:
  printsName:
    kind: shell
    spec:
      command: echo Ada
conditions:
  checkIfFileExistsWithName:
    kind: shell
    # Implicit instruction (only source)
    # sourceid: printsName
    spec:
      # Should execute the command ""test -f Ada"" (e.g. tests if the file "Ada" exists)
      command: test -f

Example with source input disabled:

# Sources defined here
# ...
conditions:
  checkIfFileExistsWithName:
    kind: shell
    disablesourceinput: true
    spec:
      # Should execute the command "test -f pom.xml" (e.g. tests if the file "pom.xml" exists)
      # There are no source value appended
      command: test -f pom.xml

This example checks if a Docker Image is published in the registry. It verifies that the docker image jenkinsciinfra/plugin-site-api with the tag returned from the source, exists on the DockerHub. The targets of this pipeline aren’t executed if this condition fails.

sources:
  tagVersion:
    kind: shell
    spec:
      command: echo v1.0.0

conditions:
  IsDockerImagePublished:
    name: |
      Is the Docker Image
      'jenkinsciinfra/plugin-site-api:{{ source `tagVersion` }}
      published on the registry?
    kind: dockerimage
    sourceid: tagVersion
    spec:
      image: "jenkinsciinfra/plugin-site-api"

# The targets defined below are not executed if
# the image 'jenkinsciinfra/plugin-site-api:v1.0.0'
# is absent on the DockerHub

Last updated on August 2, 2026

Bazelregistry

Dashboards

Docs

Updatecli

Title here

Condition

Description

Parameters

Source input

Using `failwhen`

Scoping conditions to specific targets

Examples

Condition

Description#

Parameters#

Source input#

Using failwhen#

Scoping conditions to specific targets#

Examples#

Description

Parameters

Source input

Using `failwhen`

Scoping conditions to specific targets

Examples