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.

Practice

1. What is the main purpose of the when directive in a Jenkins pipeline stage?

easy

A. To set the timeout for a stage execution

B. To define environment variables for a stage

C. To specify the agent where the stage runs

D. To control whether a stage runs based on specified conditions

Solution

1. Step 1: Understand the role of when directive

   The when directive is used to decide if a stage should run or be skipped based on conditions.

2. Step 2: Compare with other stage directives

   Other directives like environment, agent, and timeout serve different purposes unrelated to conditional execution.

3. Final Answer:

   To control whether a stage runs based on specified conditions -> Option D

4. Quick Check:

   when controls stage execution [OK]

Hint: Remember: when decides if stage runs or skips [OK]

Common Mistakes:

• Confusing when with environment
• Thinking when sets agent or timeout
• Assuming when always runs the stage

2. Which of the following is the correct syntax to run a stage only on the 'main' branch using the when directive?

easy

A. when {
branch 'main'
}

B. when {
branch == 'main'
}

C. when {
if (branch == 'main')
}

D. when {
branch: 'main'
}

Solution

1. Step 1: Recall correct when syntax for branch condition

   The correct syntax uses branch 'branchName' inside when block without operators or colons.

2. Step 2: Identify syntax errors in other options

   Options B and C use invalid operators or expressions; D uses colon which is incorrect in this context.

3. Final Answer:

   when { branch 'main' } -> Option A

4. Quick Check:

   Use branch 'name' syntax [OK]

Hint: Use branch 'name' without operators in when [OK]

Common Mistakes:

• Using comparison operators inside when
• Adding colons or equal signs incorrectly
• Writing if statements inside when

3. Given the following Jenkins pipeline snippet, what will happen if the branch is 'feature'?

stage('Deploy') {
  when {
    branch 'main'
  }
  steps {
    echo 'Deploying to production'
  }
}

medium

A. The stage will run and print 'Deploying to production'

B. The stage will be skipped and nothing will print

C. The pipeline will fail with a syntax error

D. The stage will run but print nothing

Solution

1. Step 1: Understand the when condition

   The stage runs only if the branch is 'main'. Since the branch is 'feature', the condition is false.

2. Step 2: Determine stage behavior on false condition

   When when condition is false, Jenkins skips the stage and does not execute steps.

3. Final Answer:

   The stage will be skipped and nothing will print -> Option B

4. Quick Check:

   Branch mismatch skips stage [OK]

Hint: If branch doesn't match, stage is skipped silently [OK]

Common Mistakes:

• Assuming stage runs regardless of branch
• Expecting syntax error for valid when
• Thinking stage runs but steps don't print

4. Identify the error in this Jenkins pipeline stage that uses when:

stage('Test') {
  when {
    branch == 'dev'
  }
  steps {
    echo 'Running tests'
  }
}

medium

A. The stage name 'Test' is not allowed

B. Missing agent directive for the stage

C. Using '==' operator inside when is invalid syntax

D. The steps block should be inside when

Solution

1. Step 1: Check when syntax for branch condition

   The when directive expects branch 'name' without operators like '=='.

2. Step 2: Validate other parts of the stage

   Missing agent is allowed if inherited; steps must be outside when; stage name is valid.

3. Final Answer:

   Using '==' operator inside when is invalid syntax -> Option C

4. Quick Check:

   No operators in when branch condition [OK]

Hint: No operators like '==' inside when branch check [OK]

Common Mistakes:

• Using comparison operators inside when
• Placing steps inside when
• Assuming stage name restrictions

5. You want a Jenkins stage to run only when the branch is 'release' and an environment variable DEPLOY is set to 'true'. Which when directive correctly implements this?

hard

A. when {
allOf {
branch 'release'
environment name: 'DEPLOY', value: 'true'
}
}

B. when {
branch 'release' && environment name: 'DEPLOY', value: 'true'
}

C. when {
branch 'release'
environment 'DEPLOY': 'true'
}

D. when {
anyOf {
branch 'release'
environment name: 'DEPLOY', value: 'true'
}
}

Solution

1. Step 1: Understand combining conditions in when

   To require both conditions, use allOf block combining branch and environment.

2. Step 2: Analyze each option's logic

   when {
     allOf {
       branch 'release'
       environment name: 'DEPLOY', value: 'true'
     }
   }

   correctly uses allOf.

   when {
     branch 'release' && environment name: 'DEPLOY', value: 'true'
   }

   uses invalid syntax with '&&'.

   when {
     branch 'release'
     environment 'DEPLOY': 'true'
   }

   uses invalid syntax for environment condition (missing name: and value:).

   when {
     anyOf {
       branch 'release'
       environment name: 'DEPLOY', value: 'true'
     }
   }

   uses anyOf, meaning either condition suffices.

3. Final Answer:

   when { allOf { branch 'release' environment name: 'DEPLOY', value: 'true' } } -> Option A

4. Quick Check:

   Use allOf to combine multiple when conditions [OK]

Hint: Use allOf to require all conditions true [OK]

Common Mistakes:

• Using '&&' inside when block
• Using environment 'VAR': 'value' shorthand syntax
• Using anyOf when all conditions are needed