Stage conditions with when directive in Jenkins - Step-by-Step Execution

Process Flow - Stage conditions with when directive

Start Pipeline

↓

Enter Stage

↓

Evaluate 'when' Condition

↓

Run Stage Steps

↓

Stage Complete

↓

Next Stage or End

The pipeline starts and enters a stage. The 'when' condition is checked. If true, the stage runs; if false, it skips.

Execution Sample

Jenkins

pipeline {
  agent any
  stages {
    stage('Build') {
      when { branch 'main' }
      steps { echo 'Building...' }
    }
  }
}

This pipeline runs the 'Build' stage only if the branch is 'main'.

Process Table

Step	Action	Condition Evaluated	Condition Result	Stage Action	Output
1	Start pipeline	N/A	N/A	Pipeline starts	Pipeline started
2	Enter 'Build' stage	branch == 'main'?	True	Run stage steps	Echo: Building...
3	Complete 'Build' stage	N/A	N/A	Stage complete	Stage 'Build' finished
4	Pipeline ends	N/A	N/A	Pipeline complete	Pipeline finished

💡 Pipeline ends after all stages processed

Status Tracker

Variable	Start	After Step 2	After Step 3	Final
branch	main	main	main	main
when condition (branch=='main')	N/A	True	True	True
stage status	Not started	Running	Completed	Completed

Key Moments - 2 Insights

Why does the stage run only when the branch is 'main'?

Because the 'when' directive checks if the branch equals 'main' (see execution_table step 2). If false, the stage would skip.

What happens if the 'when' condition is false?

The stage is skipped entirely, no steps run (not shown here but implied by the 'No' branch in concept_flow).

Visual Quiz - 3 Questions

Look at the execution table, what is the condition result at step 2?

A False

B N/A

C True

D Error

💡 Hint

Check the 'Condition Result' column at step 2 in the execution_table.

At which step does the stage complete?

A Step 2

B Step 3

C Step 1

D Step 4

💡 Hint

Look at the 'Stage Action' column for when the stage finishes.

If the branch was 'feature', what would happen to the stage?

A Stage is skipped

B Pipeline fails

C Stage runs normally

D Stage runs twice

💡 Hint

Refer to concept_flow where 'when' condition false leads to skipping the stage.

Concept Snapshot

Jenkins 'when' directive controls stage execution.
Syntax: when { condition }
If condition true, stage runs; else skipped.
Common conditions: branch, environment, expression.
Use to run stages selectively based on context.

Full Transcript

This visual execution shows how Jenkins pipeline stages use the 'when' directive to decide if they run. The pipeline starts, enters a stage, and evaluates the 'when' condition. If the condition is true, the stage steps execute; if false, the stage is skipped. The example uses a branch condition to run the 'Build' stage only on the 'main' branch. Variables like branch and stage status change as the pipeline progresses. Key moments clarify why stages run or skip based on the condition. Quiz questions test understanding of condition results and stage flow.