Docs

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

NameTypeDescriptionRequired
dependsonarray

“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”.
disablesourceinputboolean
failwhenboolean
kindstringkind specifies the conditions resource kind
namestringname specifies the resource name
scmidstringscmid specifies the scm configuration key associated to the current resource
sourceidstring
specobjectspec specifies parameters for a specific conditions kind
transformersarraytransformers defines how the default input value need to be transformed
    addprefixstringAddPrefix adds a prefix to the transformer input value
    addsuffixstringAddSuffix adds a suffix to the transformer input value
    findstringFind searches for a specific value if it exists and return false if it doesn’t
    findsubmatchobjectFind searches for a specific value if it exists then return the value using regular expression[pattern]
    jsonmatchobject[key]
    quotebooleanQuote add quote around the value
    replacerobjectReplacer specifies what value needs to be changed and how[from to]
    replacersarrayReplacers specifies a list of replacer instruction
    semverincstringSemvVerInc specifies a comma separated list semantic versioning component that needs to be upgraded.
    trimprefixstringTrimPrefix removes a prefix to the transformer input value
    trimsuffixstringTrimSuffix removes the suffix from the transformer input value
    unquotebooleanUnquote remove quotes around the value

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 July 30, 2026
Prev
Bazelregistry
Next
Cargo Package