Jenkinsfile per branch - Deep Dive

Overview - Jenkinsfile per branch

What is it?

A Jenkinsfile per branch means having a separate Jenkinsfile in each branch of your source code repository. Each Jenkinsfile defines the build and deployment steps specific to that branch. This allows different branches to have customized pipelines that suit their development stage or purpose. It helps teams manage workflows for features, fixes, or releases independently.

Why it matters

Without Jenkinsfiles per branch, all branches share the same pipeline, which can cause problems when different branches need different build or deployment steps. This can lead to failed builds, wasted time, or incorrect deployments. Having a Jenkinsfile per branch lets teams safely experiment, test new pipeline ideas, or handle special cases without affecting others. It improves flexibility and reduces risk in continuous integration and delivery.

Where it fits

Before learning this, you should understand basic Jenkins concepts like pipelines and Jenkinsfiles. You should also know how branches work in version control systems like Git. After this, you can explore advanced pipeline features like shared libraries, multi-branch pipelines, and pipeline as code best practices.

Mental Model

Core Idea

Each branch carries its own pipeline instructions, letting Jenkins run builds tailored to that branch’s needs.

Think of it like...

It's like each branch having its own recipe card in a cookbook. Even though the cookbook is shared, each recipe can be different depending on the dish you want to make.

Repository
├── main branch
│   └── Jenkinsfile (production pipeline)
├── feature branch
│   └── Jenkinsfile (feature-specific pipeline)
└── bugfix branch
    └── Jenkinsfile (bugfix pipeline)

Jenkins reads the Jenkinsfile from the checked-out branch to run the pipeline.

Build-Up - 7 Steps

1

Foundation

What is a Jenkinsfile

Concept: Introduce the Jenkinsfile as a script that defines the steps Jenkins runs to build and deploy code.

A Jenkinsfile is a text file named 'Jenkinsfile' stored in your source code repository. It tells Jenkins what to do when building your project, like compiling code, running tests, or deploying. It uses a simple scripting language called Groovy with special Jenkins commands.

Result

You have a file that controls your build process in code form, versioned alongside your project.

Understanding Jenkinsfile basics is key because it lets you automate builds and keep build logic close to your code.

2

Foundation

Branches in Version Control

Concept: Explain what branches are and how they let developers work on different versions of code simultaneously.

Branches are copies of your code where you can make changes without affecting the main project. For example, you might have a 'main' branch for stable code and 'feature' branches for new work. Each branch can have different files or changes.

Result

You can work on multiple versions of your project safely and independently.

Knowing branches lets you understand why different pipeline behaviors might be needed per branch.

3

Intermediate

Why Use Jenkinsfile Per Branch

🤔Before reading on: do you think one Jenkinsfile can handle all branches well, or is a separate Jenkinsfile per branch better? Commit to your answer.

Concept: Show the benefits of having a Jenkinsfile in each branch to customize pipelines per branch.

If all branches share one Jenkinsfile, you must make it generic enough for all cases, which can be complex and error-prone. With a Jenkinsfile per branch, you can tailor the pipeline to the branch’s purpose. For example, a feature branch might run extra tests, while the main branch deploys to production.

Result

Each branch runs a pipeline that fits its needs, reducing errors and improving flexibility.

Knowing why per-branch Jenkinsfiles exist helps you design pipelines that match your team's workflow and reduce build failures.

4

Intermediate

How Jenkins Detects Jenkinsfile Per Branch

🤔Before reading on: do you think Jenkins uses a single Jenkinsfile for all branches or reads the Jenkinsfile from each branch? Commit to your answer.

Concept: Explain how Jenkins multi-branch pipeline jobs automatically find the Jenkinsfile in each branch.

Jenkins multi-branch pipeline jobs scan your repository for branches. For each branch, Jenkins checks out the code and looks for a Jenkinsfile in that branch. It then runs the pipeline defined there. This means Jenkins dynamically uses the Jenkinsfile that belongs to the branch it is building.

Result

Jenkins runs branch-specific pipelines without manual configuration per branch.

Understanding this detection mechanism clarifies how Jenkins supports multiple pipelines from one job.

5

Intermediate

Managing Different Jenkinsfiles Safely

🤔Before reading on: do you think changes to Jenkinsfiles in feature branches affect the main branch pipeline immediately? Commit to your answer.

Concept: Teach how changes to Jenkinsfiles in branches affect only that branch until merged.

Because each branch has its own Jenkinsfile, changes to a Jenkinsfile in a feature branch only affect builds of that branch. The main branch pipeline stays stable until you merge changes. This isolation lets teams experiment safely without breaking the main pipeline.

Result

Pipeline changes are isolated per branch, reducing risk.

Knowing this isolation helps teams confidently improve pipelines without fear of breaking production builds.

6

Advanced

Handling Shared Pipeline Logic Across Branches

🤔Before reading on: do you think duplicating Jenkinsfiles per branch is the best way to share common pipeline steps? Commit to your answer.

Concept: Introduce shared libraries or common scripts to avoid repeating code in multiple Jenkinsfiles.

While each branch can have its own Jenkinsfile, duplicating common steps leads to maintenance headaches. Jenkins supports shared libraries—central scripts stored separately that Jenkinsfiles can call. This way, branches keep their own Jenkinsfile but reuse common logic, making updates easier and consistent.

Result

You maintain DRY (Don't Repeat Yourself) pipelines with per-branch customization.

Understanding shared libraries prevents pipeline sprawl and keeps maintenance manageable in multi-branch setups.

7

Expert

Pitfalls and Advanced Branch Pipeline Strategies

🤔Before reading on: do you think Jenkins always picks the Jenkinsfile from the branch being built, or can configuration cause it to use a different file? Commit to your answer.

Concept: Reveal subtle issues like Jenkinsfile caching, branch indexing delays, and advanced strategies like conditional pipeline loading.

Sometimes Jenkins caches pipeline definitions, causing it to run outdated Jenkinsfiles. Also, branch indexing might delay detecting new branches or Jenkinsfile changes. Experts use techniques like pipeline caching control, scripted conditional loading of pipeline parts, or even external pipeline definitions to handle complex workflows. These strategies improve reliability and performance in large projects.

Result

You can avoid subtle bugs and optimize pipeline execution in complex multi-branch environments.

Knowing these advanced details helps prevent hard-to-debug pipeline failures and improves CI/CD robustness.

Under the Hood

When Jenkins runs a multi-branch pipeline job, it scans the repository for branches. For each branch, Jenkins checks out the code at that branch's commit. It then looks for a Jenkinsfile in the root directory of that branch. Jenkins parses and executes the Jenkinsfile script in its Groovy-based pipeline engine. The pipeline steps run on Jenkins agents as defined. This process repeats independently for each branch, allowing different pipeline scripts per branch.

Why designed this way?

This design allows teams to keep pipeline code versioned alongside application code, ensuring pipeline changes are tested with the code changes. It avoids central pipeline configuration that can become outdated or disconnected. Multi-branch pipelines automate discovery of branches and their Jenkinsfiles, reducing manual setup. Alternatives like a single global pipeline were less flexible and risked breaking builds when pipeline changes were made.

Multi-branch Pipeline Job
┌─────────────────────────────┐
│ Jenkins Multi-branch Job     │
│                             │
│ ┌───────────────┐           │
│ │ Branch Scanner│           │
│ └──────┬────────┘           │
│        │                    │
│  ┌─────▼─────┐              │
│  │ Branch A   │              │
│  │ Checkout   │              │
│  │ Jenkinsfile│              │
│  └─────┬─────┘              │
│        │                    │
│  ┌─────▼─────┐              │
│  │ Run Pipeline│             │
│  └───────────┘              │
│                             │
│  ┌───────────────┐          │
│  │ Branch B      │          │
│  │ Checkout     │          │
│  │ Jenkinsfile  │          │
│  └─────┬────────┘          │
│        │                   │
│  ┌─────▼─────┐             │
│  │ Run Pipeline│            │
│  └───────────┘             │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Jenkins always use the Jenkinsfile from the main branch for all builds? Commit yes or no.

Common Belief: Jenkins uses the Jenkinsfile from the main branch for all builds, regardless of which branch is built.

Reality: Jenkins uses the Jenkinsfile from the specific branch it is building, not always from main.

Why it matters: If you assume Jenkins uses main's Jenkinsfile, you might expect pipeline changes in feature branches to run immediately, but they won't, causing confusion and failed builds.

Quick: Can you safely edit the Jenkinsfile in a feature branch without affecting main branch builds? Commit yes or no.

Common Belief: Editing the Jenkinsfile in a feature branch will immediately affect the main branch pipeline.

Reality: Changes to Jenkinsfiles in feature branches only affect builds of that branch until merged into main.

Why it matters: Believing otherwise can cause fear of pipeline changes and slow down development and testing of new pipeline features.

Quick: Is duplicating Jenkinsfiles in every branch the best way to share pipeline code? Commit yes or no.

Common Belief: Each branch should have a fully independent Jenkinsfile with no shared code to avoid dependencies.

Reality: Duplicating Jenkinsfiles leads to maintenance problems; shared libraries or common scripts are better for reusing pipeline code.

Why it matters: Ignoring shared code leads to inconsistent pipelines and extra work updating multiple Jenkinsfiles.

Quick: Does Jenkins always immediately detect new branches and Jenkinsfile changes? Commit yes or no.

Common Belief: Jenkins instantly detects new branches and Jenkinsfile updates without delay.

Reality: Jenkins may delay detecting new branches or Jenkinsfile changes due to branch indexing schedules or caching.

Why it matters: Assuming instant detection can cause confusion when builds don't trigger or run outdated pipelines.

Expert Zone

1

Jenkins caches pipeline definitions per branch which can cause stale pipeline runs if not refreshed properly.

2

Branch indexing frequency affects how quickly Jenkins discovers new branches or Jenkinsfile changes, impacting CI responsiveness.

3

Using conditional logic inside Jenkinsfiles can allow a single Jenkinsfile to behave differently per branch, reducing duplication but increasing complexity.

When NOT to use

Using Jenkinsfile per branch is not ideal if your pipeline logic is almost identical across branches and you want centralized control. In such cases, use a single Jenkinsfile with parameters or shared libraries to handle variations. Also, for very large repositories with many branches, managing many Jenkinsfiles can become complex; consider centralized pipeline management tools.

Production Patterns

In production, teams use multi-branch pipeline jobs that automatically discover branches and run their Jenkinsfiles. They combine this with shared libraries for common steps and use branch naming conventions to trigger different behaviors. Feature branches often have pipelines that run tests only, while release branches deploy to staging or production. Teams also automate branch cleanup to remove old pipelines.

Connections

Git Branching

Builds-on

Understanding Git branching deeply helps grasp why different branches need different Jenkinsfiles and how pipeline changes flow through merges.

Infrastructure as Code (IaC)

Similar pattern

Both Jenkinsfiles per branch and IaC keep configuration versioned with code, enabling reproducible and isolated environments or pipelines.

Software Configuration Management

Builds-on

Managing Jenkinsfiles per branch is a form of configuration management, showing how code and its build instructions evolve together.

Common Pitfalls

#1 Editing Jenkinsfile in feature branch but expecting main branch builds to change immediately.

Wrong approach:

Modify Jenkinsfile in feature branch and assume main branch pipeline uses it without merging.

Correct approach:

Test Jenkinsfile changes by running builds on the feature branch itself; merge to main only when ready.

Root cause:

Misunderstanding that Jenkins uses the Jenkinsfile from the branch being built, not from main.

#2 Copy-pasting entire Jenkinsfiles into every branch causing duplication.

Wrong approach:

Each branch has a full Jenkinsfile copy with repeated code blocks.

Correct approach:

Use shared libraries or common scripts called by Jenkinsfiles to reuse code and reduce duplication.

Root cause:

Lack of knowledge about Jenkins shared libraries and pipeline code reuse.

#3 Assuming Jenkins instantly detects new branches and Jenkinsfile changes.

Wrong approach:

Expect builds to trigger immediately after pushing new branch or Jenkinsfile update without configuring branch indexing.

Correct approach:

Configure branch indexing frequency and manually trigger indexing if needed to detect changes promptly.

Root cause:

Not understanding Jenkins multi-branch pipeline indexing and caching behavior.

Key Takeaways

A Jenkinsfile per branch lets each branch define its own build and deployment steps, improving flexibility and safety.

Jenkins multi-branch pipeline jobs automatically detect branches and use the Jenkinsfile from the branch being built.

Changes to Jenkinsfiles in feature branches affect only that branch until merged, isolating pipeline experiments.

Shared libraries help avoid duplicating pipeline code across branches, making maintenance easier.

Advanced Jenkins users manage caching, indexing, and conditional logic to optimize multi-branch pipeline performance.