Conditional Workflows

Conditional workflow in Pipelines enables you to choose if a step executes or skips based on certain conditions set for the previous upstream step. This means, when the workflow reaches a conditional step, it can choose different workflow paths based on the step’s status. This provides more flexibility in the execution logic of a pipeline.

Note

Conditional workflow can be applied to any Pipelines step.

Step Status Conditional Workflow

With the status conditional workflow, you can configure a step to execute only if an input step’s status, during its current run, is satisfied. You can configure any number of statuses for a step.

YAML Schema

    steps:
      - name: <step_name>
        type: <step_type>
        configuration:
                  allowFailure: boolean         #optional
          inputSteps:
            - name: <step_name>
              status:
                - <terminal_status>
                - <terminal_status>
                - <terminal_status>

Note

It is important to note that the status of an input step in the current run only is considered for conditional workflows. If a step is not part of the current run, it is always assumed that the condition for that input step is met.

Adding Conditional Workflow for Steps

To add a conditional workflow for a step:

In the inputSteps section of a step, add the status property.

Add any of these values:

success
failure
error
cancelled
skipped
unstable
timeout

Note

Ensure that the values are in lowercase and use the same spelling as shown above. Any deviation from this will cause the pipeline source sync to fail.

Example: In this example:

step_B has only one status: success
step_C has multiple statuses: failure, skipped, cancelled

      - name: step_A
        type: Bash
        configuration:
                  allowFailure: boolean         #optional
          inputSteps:
            - name: step_B
              status:
                - success
            - name: step_C
              status:
                - failure
                - skipped
                - cancelled

allowFailure
Optional: If you do not want a particular step to contribute to the final status of the run, you can add allowFailure: true to the configuration section of that step. When this option is used, even when a step fails or is skipped, the final status of the run is not affected.
For example, a pipeline contains two steps S1 and S2:
- Scenario 1: Step S2 is a cleanup step and its status is irrelevant. The overall run status should be determined by S1’s status and S2’s status should be ignored. In this case, add allowFailure: true to S2, since this is purely a cleanup step and only S1’s status should be taken into consideration.
- Scenario 2: Step S1 has been configured to fail as part of the workflow. However S2 runs even if S1 fails and the run is not to be considered a failure. The run’s final status should mirror S2’s status since S1’s status does not interrupt the flow. In this case, add allowFailure: true to S1 since S1’s failure is a known possibility and expected, and that should not affect the final status of the run.

For more examples, see allowFailure Examples.

Run Variable Conditional Workflow

Create a condition based on the values of add_run_variables environment variable, so that a step can be skipped based on dynamically set variables before it gets assigned to a node.

Note

When using a condition, boolean values must be enclosed in quotes.

Examples:

condition: 'trigger == "true"'
condition: "trigger == 'true'"
condition: trigger == 'true'
condition: trigger == "true"

Note

Pipelines environment variables cannot be added as a condition.Pipelines Environment Variables

YAML Schema

    steps:
      - name: <step_name>
        type: <step_type>
        execution:
          onExecute:
            - add_run_variables 'key=value'
      - name: <step_name>
        type: <step_type>
        configuration:
          condition: 'key == value' // Any logical boolean expression that results in a boolean
          inputSteps:
            - name: <step_name>

Example

pipelines:
  - name: Example
    steps:
      - name: step1
        type: Bash
        execution:
          onExecute:
            - echo 'step1'
            - add_run_variables 'var1=1'
      - name: step2
        type: Bash
        configuration:
          condition: 'var1 == 1' // Any logical boolean expression that results to a boolean
          inputSteps:
            - name: step1
        execution:
          onExecute:
            - echo 'success'

Environment Variables Conditional Workflow

Create a conditional workflow based on environment variables defined in the configuration section of your pipelines YAML file. The step executes when the declared condition is met.

Example

pipelines:
  - name: myPipelines
    configuration:
      environmentVariables:
        readOnly:
          new_env:
            default: 1
            allowCustom: true
    steps:
      - name: step1
        type: Bash
        configuration:
          environmentVariables:
              new_env:
                default: 2
                #allowCustom: true
          condition: new_env == 2
        execution:
          onExecute:
            - echo $new_env
      - name: step2
        type: Bash
        configuration: 
          condition: new_env == 1
          inputSteps:
            - name: step1
        execution:
          onExecute:
            - echo 'success'

newVersionOnly Conditional Workflow

Whenever a resource undergoes a change, its version is updated and the dependent step is triggered. This is the default behavior for all input resources. To skip steps in a run when input resources are not updated, add the newVersionOnly tag and set it as true. During a run, the step is triggered only when the resource is updated. If the resource is not updated, the step is skipped and all the downstream steps are skipped as well.

Example 1 - newVersionOnly

pipelines:
  - name: java_pipeline
    steps:
      - name: step_1
        type: Bash
        configuration:
          inputResources:
            - name: my_app_repo
            - newVersionOnly: true
        execution:
          onExecute:
            - pushd $res_my_app_repo_resourcePath
            - ./execute.sh
            - popd

resources:
  - name: new_resource
    type: PropertyBag
    configuration:
      runNumber: 0

pipelines:
  - name: pipeline_01
    steps:
      - name: step_input
        type: Bash
        configuration:
          outputResources:
            - name: new_resource
        execution:
          onExecute:
            #- write_output new_resource runNumber=${run_number}
            - echo "test"

      - name: step1      
        type: Bash
        configuration:
          inputResources:
            - name: new_resource
              newVersionOnly: true
        execution:
          onExecute:
            - echo "test"

      - name: step2
        type: Bash
        configuration:
          inputResources:
            - name: new_resource
        execution:
          onExecute:
            - echo "test"

Viewing Run Logs

When you run a pipeline, in addition to the other logs, the logs for steps with conditional workflow provide information about the skipped steps.

To view these logs, go to the Pipeline Run Logs view, click the skipped step to display the logs for the current run.

Examples

Example 1

In this example:

Step B is triggered only if step A succeeds (default behavior), and step C is triggered only if step A is in failed, error, or timeout status.
Step B does not need any special configuration as the default behavior is to trigger a dependent step if the previous step succeeds.
Step A also does not need any special configuration since the step itself does not decide the downstream workflow path.

YAML

  - name: demo_conditional
    steps:
      - name: step_A
        type: Bash
        configuration:
          inputResources:
            - name: script_conditional
        execution:
          onExecute:
            - echo "Executing step_A"
            - printenv
     
      - name: step_B
        type: Bash
        configuration:
          inputSteps:
            - name: step_A
        execution:
          onExecute:
            - echo "Executing step_B"
            - printenv

      - name: step_C
        type: Bash
        configuration:
          inputSteps:
            - name: step_A
              status:
                - failure
                - error
                - timeout
        execution:
          onExecute:
            - echo "Executing step_C"
            - printenv

Example 2

In this example, Step S is triggered if Step Q succeeds and Step R fails. However, if both Step Q and Step R succeed or fail during the run, Step S is not triggered and it is skipped.

YAML

      - name: step_S
        type: Bash
        configuration:
          inputSteps:
            - name: step_Q
              status:
                - success
            - name: step_R
              status:
                - failure
        execution:
          onExecute:
            - echo "Executing step_S"
            - printenv

Example 3

In this example, Step O is triggered if Step M succeeds and Step N fails. However, since Step N is not part of the current run, Step O is triggered when Step M succeeds and Step N's status is ignored.

YAML

      - name: step_O
        type: Bash
        configuration:
          inputSteps:
            - name: step_M
              status:
                - success
            - name: step_N
              status:
                - failure
        execution:
          onExecute:
            - echo "Executing step_O"
            - printenv

Example 4 - Using Environment Variable

The step_<inputStepName>_statusName, which is an environment variable that is automatically made available at runtime, can be used in conjunction with conditional workflows. This step_<inputStepName>_statusName environment variable is useful for fetching the status of any input step, especially when working with Jenkins.

YAML

resources:
  - name: script_gh
    type: GitRepo
    configuration:
      path: jfrog/sample-script
      gitProvider: myGithub
      branches:
        include: ^{{gitBranch}}$

pipelines:     
  - name: simple_jenkins_demo
    steps:
      - name: jenkins
        type: Jenkins
        configuration:
          inputResources:
            - name: script_gh
          jenkinsJobName: testPipeline
          integrations:
            - name: myJenkins
      
      - name: step_A
        type: Bash
        configuration:
          inputSteps:
            - name: jenkins
              status:
                - failure
                - error
                - timeout
        execution:
          onExecute:
            - echo "Executing step_A"
            - if [ $step_jenkins_statusName == "failure" ]; then  echo "Do something"; fi
            - if [ $step_jenkins_statusName == "error" ]; then  echo "Do something else"; fi
     
      - name: simple_conditional_B
        type: Bash
        configuration:
          inputSteps:
            - name: jenkins
              status:
                - failure
                - error
        execution:
          onExecute:
            - echo "Executing simple_conditional_B"
            - printenv

allowFailure Examples

Example 1

Step1 is configured for success and step2 for failure. Step2 is allowed to run when step1 fails and the final status of the run is success.

pipelines:
  - name: PIPE_9455_Workflow_03
    steps:
      - name: step1
        type: Bash
        execution:
          onExecute:
            - echo 'step1'
      - name: step2
        type: Bash
        configuration:
          allowFailure: true
          inputSteps:
          - name: step1
            status:
              - success
              - error
              - failure
              - timeout
        execution:
          onExecute:
            - echo 'success'
            - exit 1

Example 2

Step1 is configured for failure and step2 for success. Step2 is allowed to run when step1 fails and the final status of the run is success.

pipelines:
  - name: PIPE_9455_Workflow_05
    steps:
      - name: step1
        type: Bash
        configuration:
          allowFailure: true
        execution:
          onExecute:
            - echo 'step1'
            - exit 1
      - name: step2
        type: Bash
        configuration:
          inputSteps:
          - name: step1
            status:
              - success
              - error
              - failure
              - timeout
        execution:
          onExecute:
            - echo 'success'

Example 3

Step1 is configured for success and step2 for failure. When triggered, the final status of the run is failure.

pipelines:
  - name: PIPE_9455_Workflow_03
    steps:
      - name: step1
        type: Bash
        configuration:
          allowFailure: true
        execution:
          onExecute:
            - echo 'step1'
      - name: step2
        type: Bash
        configuration:
          inputSteps:
          - name: step1
            status:
              - success
              - error
              - failure
              - timeout
        execution:
          onExecute:
            - echo 'failure'
            - exit 1