# Condition<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

== Description

A "condition" stage defines whether to run the link:../target["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,Scoping conditions to specific targets>>.

== Parameters

{{< coreparameters "conditions" >}}

=== 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]
=== 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:

[source,yaml]
----
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:

[source,yaml]
----
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:

[source,yaml]
----
# 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.

[source,yaml]
----
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
----