Conditional execution

Skip a stage or step at runtime by setting a condition that must evaluate to true for it to run.

Conditional execution lets you skip a stage or step based on a condition evaluated at runtime. If the condition evaluates to false, Harness skips it and marks it as not executed; execution continues from the next stage or step.

Use conditional execution to:

• Run a deploy stage only when the pipeline has succeeded up to that point

• Always run a cleanup stage regardless of prior failures

• Skip a stage when a pipeline input does not match a target value

What you will learn

• How to skip a stage or step at runtime using the if key and a JEXL condition

• What the built-in base conditions (OnPipelineSuccess, OnPipelineFailure, Always) do

• How to combine conditions and gate execution on a pipeline input value

• How skipped stages behave and what happens to their outputs

---

YAML

Use the if key on a stage or step. The condition is a JEXL expression:

stages:
  - name: deploy-prod
    id: deploy_prod
    if: <+OnPipelineSuccess>
    steps:
      - name: deploy
        id: deploy
        run:
          script: ./deploy-prod.sh

If the expression resolves to false, the stage is skipped entirely. No steps run, and no failure is recorded.

---

Base execution conditions

These built-in JEXL conditions control when a stage runs relative to the pipeline state:

Condition	Runs when
<+OnPipelineSuccess>	All previous stages succeeded (default behavior)
<+OnPipelineFailure>	At least one previous stage failed
<+Always>	Always runs, regardless of prior stage status

# Run only if prior stages succeeded (same as default)
if: <+OnPipelineSuccess>

# Run a cleanup stage even when previous stages failed
if: <+Always>

# Run a rollback stage only on failure
if: <+OnPipelineFailure>

---

Combine with an expression

You can combine a base condition with an additional JEXL expression using &&:

# Skip this stage (force-skip using && false)
if: <+OnPipelineSuccess> && false

To gate on a pipeline input value, wrap the input expression in single quotes so the resolved value becomes a JEXL string literal:

pipeline:
  inputs:
    env:
      type: string
      default: production
  stages:
    - name: deploy-prod
      id: deploy_prod
      if: "'<+inputs.env>' == 'production'"
      steps:
        - name: deploy
          id: deploy
          run:
            script: ./deploy-prod.sh
    - name: deploy-staging
      id: deploy_staging
      if: "'<+inputs.env>' == 'staging'"
      steps:
        - name: deploy
          id: deploy
          run:
            script: ./deploy-staging.sh

When comparing a pipeline input value, wrap <+inputs.varName> in single quotes: "'<+inputs.env>' == 'production'". Without the outer quotes, JEXL treats the resolved value as an identifier rather than a string literal, causing an expression evaluation error.

---

Behavior

• A skipped stage does not count as a failure.

• Downstream stages that depend on a skipped stage's outputs will receive empty values for those outputs.

• Conditional execution is evaluated before the stage starts; it cannot be based on that stage's own steps.

In a parallel group, each stage has its own condition. One stage in the group can be skipped while the others still run.

---

Next steps

• Go to On failure to control what happens when a stage fails.

• Go to Stage inputs & outputs to reference stage outputs in conditions.

• Go to Pipelines overview to review the pipeline model.