# 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 (`true`).

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

== Parameters

{{< coreparameters "conditions" >}}

=== 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.

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