Stage conditions with when directive in Jenkins - Mini Project: Build & Apply

Stage conditions with when directive

📖 Scenario: You are setting up a Jenkins pipeline for a simple project. You want to control which stages run based on the branch name. This helps avoid running unnecessary steps on branches where they are not needed.

🎯 Goal: Build a Jenkins pipeline script with two stages. The first stage always runs. The second stage runs only when the branch is main. You will use the when directive to add this condition.

📋 What You'll Learn

Create a Jenkins pipeline with two stages named Build and Deploy

The Build stage should always run

The Deploy stage should run only when the branch is main

Use the when directive with branch 'main' condition

Print simple messages in each stage to show they ran

💡 Why This Matters

🌍 Real World

In real projects, controlling which stages run based on branch names helps save time and resources by skipping unnecessary steps on feature or development branches.

💼 Career

Understanding Jenkins pipeline conditions is essential for DevOps roles to automate builds and deployments efficiently and safely.

1

Create the basic pipeline with a Build stage

Write a Jenkins pipeline script that defines a pipeline block with an agent any and a single stage named Build. Inside the Build stage, add a steps block that runs echo 'Building the project'.

Jenkins

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                // Your code here
            }
        }
    }
}

Hint

Use pipeline and agent any to start. Then add one stage named Build with steps that echo a message.

2

Add a Deploy stage with a when condition

Add a second stage named Deploy after the Build stage. Inside the Deploy stage, add a when directive that runs the stage only when the branch is main. Use branch 'main' inside when. Add a steps block that runs echo 'Deploying to production'.

Jenkins

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building the project'
            }
        }
        // Add Deploy stage with when condition here
    }
}

Hint

Use when { branch 'main' } inside the Deploy stage to run it only on the main branch.

3

Add an environment variable for the branch name

Inside the pipeline block but outside stages, add an environment block that defines a variable BRANCH_NAME set to env.BRANCH_NAME. This will hold the current branch name.

Jenkins

pipeline {
    agent any
    // Add environment block here
    stages {
        stage('Build') {
            steps {
                echo 'Building the project'
            }
        }
        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                echo 'Deploying to production'
            }
        }
    }
}

Hint

Use environment { BRANCH_NAME = env.BRANCH_NAME } inside the pipeline block to capture the branch name.

4

Print the branch name in the Build stage

Inside the Build stage's steps block, add a line to print the branch name using echo "Building branch: ${BRANCH_NAME}".

Jenkins

pipeline {
    agent any
    environment {
        BRANCH_NAME = env.BRANCH_NAME
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building the project'
                // Your code here
            }
        }
        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                echo 'Deploying to production'
            }
        }
    }
}

Hint

Use echo "Building branch: ${BRANCH_NAME}" inside the Build stage's steps to show the branch name.

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