Branch selection and branch specifier in Jenkins - Step-by-Step Execution

Process Flow - Branch selection and branch specifier

Start Jenkins Pipeline

↓

Read Branch Specifier

↓

Check Branch Exists?

No→Fail or Wait

Yes↓

Checkout Branch

↓

Run Pipeline Steps on Selected Branch

↓

End Pipeline

The Jenkins pipeline reads the branch specifier, checks if the branch exists, then checks out that branch to run the pipeline steps.

Execution Sample

Jenkins

pipeline {
  agent any
  stages {
    stage('Checkout') {
      steps {
        checkout([$class: 'GitSCM', branches: [[name: 'refs/heads/main']]])
      }
    }
  }
}

This pipeline checks out the 'main' branch from Git before running further steps.

Process Table

Step	Action	Branch Specifier	Branch Exists?	Result
1	Start Pipeline	refs/heads/main	N/A	Pipeline started
2	Read Branch Specifier	refs/heads/main	N/A	Branch specifier read
3	Check Branch Exists	refs/heads/main	Yes	Branch found
4	Checkout Branch	refs/heads/main	Yes	Branch 'main' checked out
5	Run Pipeline Steps	refs/heads/main	Yes	Pipeline runs on 'main' branch
6	End Pipeline	refs/heads/main	Yes	Pipeline completed

💡 Pipeline ends after running steps on the specified branch.

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
branchSpecifier	undefined	refs/heads/main	refs/heads/main	refs/heads/main	refs/heads/main
branchExists	undefined	undefined	true	true	true
checkoutStatus	undefined	undefined	undefined	success	success

Key Moments - 2 Insights

Why does the pipeline fail if the branch specifier is incorrect?

Because in the execution_table at Step 3, if 'branchExists' is 'No', Jenkins cannot checkout the branch, causing failure.

Can the branch specifier be changed dynamically during the pipeline?

No, the branch specifier is read at the start (Step 2) and used for checkout; changing it later won't affect the already checked out code.

Visual Quiz - 3 Questions

Look at the execution table, what is the branchExists value at Step 3?

A No

B Yes

C Undefined

D Error

💡 Hint

Check the 'branchExists' column in row for Step 3 in execution_table.

At which step does Jenkins perform the actual branch checkout?

A Step 2

B Step 3

C Step 4

D Step 5

💡 Hint

Look for 'Checkout Branch' action in execution_table.

If the branch specifier was 'refs/heads/dev', how would the variable 'branchSpecifier' change after Step 2?

A It would be 'refs/heads/dev'

B It would be 'refs/heads/main'

C It would be undefined

D It would be empty string

💡 Hint

Refer to variable_tracker 'branchSpecifier' value after Step 2.

Concept Snapshot

Jenkins branch specifier defines which Git branch to checkout.
It uses syntax like 'refs/heads/main' to specify branches.
Pipeline reads this specifier early, checks if branch exists.
If branch exists, Jenkins checks it out and runs pipeline steps.
Incorrect specifier causes checkout failure and pipeline error.

Full Transcript

In Jenkins pipelines, the branch specifier tells Jenkins which Git branch to use. The pipeline starts by reading this specifier, for example 'refs/heads/main'. Jenkins then checks if this branch exists in the repository. If it does, Jenkins checks out the branch so the pipeline can run on that code. If the branch does not exist, the pipeline fails because it cannot checkout the code. The branch specifier is fixed at the start of the pipeline and cannot be changed dynamically during execution. This process ensures the pipeline runs on the correct branch code.

Practice

1. What does the Branch Specifier field in Jenkins do?

easy

A. It tells Jenkins which branch or branches to build.

B. It specifies the build timeout duration.

C. It defines the build environment variables.

D. It sets the Jenkins user permissions.

Solution

1. Step 1: Understand the purpose of Branch Specifier

   The Branch Specifier is used to tell Jenkins which branch or branches to build from the source code repository.

2. Step 2: Eliminate unrelated options

   Timeout, environment variables, and user permissions are unrelated to branch selection.

3. Final Answer:

   It tells Jenkins which branch or branches to build. -> Option A

4. Quick Check:

   Branch Specifier = Select branch to build [OK]

Hint: Branch Specifier selects branches to build in Jenkins [OK]

Common Mistakes:

• Confusing branch specifier with build timeout
• Thinking it sets environment variables
• Assuming it controls user permissions

2. Which of the following is the correct syntax to specify the master branch in Jenkins Branch Specifier?

easy

A. refs/remotes/master

B. refs/tags/master

C. refs/heads/master

D. refs/branches/master

Solution

1. Step 1: Recall Git reference format for branches

   Branches in Git are referenced as refs/heads/branch-name. So the master branch is refs/heads/master.

2. Step 2: Identify incorrect references

   refs/tags/ is for tags, refs/remotes/ is for remote tracking branches, and refs/branches/ is not a valid Git ref.

3. Final Answer:

   refs/heads/master -> Option C

4. Quick Check:

   Branch refs start with refs/heads/ [OK]

Hint: Use refs/heads/branch-name for branch specifier [OK]

Common Mistakes:

• Using refs/tags/ instead of refs/heads/
• Confusing remote refs with local branch refs
• Using invalid refs/branches/ prefix

3. Given the branch specifier refs/heads/feature/*, which branches will Jenkins build?

medium

A. Only the branch named exactly 'feature/*'.

B. Only the 'master' branch.

C. All branches except those starting with 'feature/'.

D. All branches starting with 'feature/', like 'feature/login' and 'feature/ui'.

Solution

1. Step 1: Understand wildcard usage in branch specifier

   The asterisk (*) acts as a wildcard matching any characters after 'feature/'. So it matches all branches starting with 'feature/'.

2. Step 2: Analyze each option

   Only the branch named exactly 'feature/*'. is incorrect because it treats '*' literally. All branches except those starting with 'feature/'. is opposite meaning. Only the 'master' branch. is unrelated.

3. Final Answer:

   All branches starting with 'feature/', like 'feature/login' and 'feature/ui'. -> Option D

4. Quick Check:

   Wildcard * matches multiple branches [OK]

Hint: Use * wildcard to match multiple branches [OK]

Common Mistakes:

• Treating * as a literal character
• Assuming it excludes matching branches
• Confusing branch names with tags

4. You set the branch specifier to refs/heads/release but Jenkins builds no branches. What is the likely problem?

medium

A. The branch name is incorrect or does not exist in the repo.

B. The Jenkins server is offline.

C. The build script has syntax errors.

D. The workspace is full.

Solution

1. Step 1: Check branch existence

   If Jenkins builds no branches, the specified branch refs/heads/release might not exist in the repository.

2. Step 2: Rule out unrelated issues

   Server offline, build script errors, or workspace full would cause different errors or failures, not silent no build.

3. Final Answer:

   The branch name is incorrect or does not exist in the repo. -> Option A

4. Quick Check:

   Branch specifier must match existing branch [OK]

Hint: Verify branch exists before setting specifier [OK]

Common Mistakes:

• Assuming Jenkins server status causes no build
• Blaming build script syntax for branch selection
• Ignoring branch existence check

5. You want Jenkins to build all branches except those starting with hotfix/. Which branch specifier pattern should you use?

hard

A. !refs/heads/*

B. refs/heads/*, !refs/heads/hotfix/*

C. refs/heads/*

D. refs/heads/hotfix/*

Solution

1. Step 1: Understand inclusion and exclusion patterns

   Jenkins supports including all branches with refs/heads/* and excluding specific branches with !refs/heads/hotfix/*.

2. Step 2: Analyze options

   refs/heads/*, !refs/heads/hotfix/* includes all branches but excludes hotfix branches. refs/heads/hotfix/* only includes hotfix branches. refs/heads/* includes all branches without exclusion. !refs/heads/* excludes all branches.

3. Final Answer:

   refs/heads/*, !refs/heads/hotfix/* -> Option B

4. Quick Check:

   Use ! to exclude branches in specifier [OK]

Hint: Use ! prefix to exclude branches in specifier [OK]

Common Mistakes:

• Not using exclusion pattern with !
• Only specifying excluded branches
• Excluding all branches accidentally