Why Stage conditions with when directive in Jenkins? - Purpose & Use Cases

The Big Idea

Discover how a simple directive can save you hours of debugging and wasted builds!

The Scenario

Imagine you have a Jenkins pipeline with many stages, and you want some stages to run only under certain conditions, like only on a specific branch or when a file changes.

Without stage conditions, you have to write complex scripts inside each stage to check these conditions manually.

The Problem

Manually checking conditions inside stages makes your pipeline scripts long and confusing.

It's easy to make mistakes, like running stages when you don't want to or skipping important ones.

This slows down your builds and wastes resources.

The Solution

The when directive lets you declare conditions clearly and simply right at the stage level.

Jenkins then automatically decides whether to run the stage or skip it, keeping your pipeline clean and efficient.

Before vs After

✗ Before

stage('Build') {
  steps {
    script {
      if (env.BRANCH_NAME == 'main') {
        // build steps
      }
    }
  }
}

✓ After

stage('Build') {
  when {
    branch 'main'
  }
  steps {
    // build steps
  }
}

What It Enables

You can create smarter pipelines that run exactly what you need, saving time and avoiding errors.

Real Life Example

For example, only run deployment stages when code is merged into the main branch, and skip them for feature branches automatically.

Key Takeaways

Manual condition checks clutter pipeline scripts and cause errors.

The when directive simplifies conditional stage execution.

This leads to cleaner, faster, and more reliable pipelines.

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