A plain-language first look before any details.

Jenkins is a free, open-source automation server that builds, tests and delivers software. Its work is written as a pipeline, a recipe stored in a text file called the Jenkinsfile. A pipeline is divided into stages, such as Build, Test and Deploy, and each stage contains steps, the single actions Jenkins performs.

Developers use branches in version control, usually Git. A branch is a separate line of work: a copy of the code where someone can experiment without disturbing the main line. A pull request is a request to merge a branch into another, and it is where teammates review changes before they are accepted.

A Multibranch Pipeline is a special kind of Jenkins job. Instead of running one pipeline, it acts like a manager that watches a whole repository. For every branch, and optionally every pull request and tag, that contains a Jenkinsfile, it creates a child job and runs that branch’s own pipeline.

This idea has become the standard way to run Jenkins for modern teams. Companies with dozens or hundreds of repositories rely on it because it scales with the code, not with the number of people available to click buttons in a web page.

The problem it solves and how the idea grew.

The problem: branches come and go

In older setups, a Jenkins job was tied to one branch. A team would create a job for the main branch, maybe another for a release branch. But modern workflows create short-lived branches for every feature and fix. Teams tried copying jobs by hand, or writing scripts that called the Jenkins interface to clone jobs. These approaches broke constantly. Jobs were forgotten, settings drifted between copies, and nobody knew which jobs were still needed.

There was a deeper problem too. When the job configuration lives in the Jenkins web page, the branch cannot change its own build. If a developer adds a new test stage in a branch, the job on the server does not know about it until an administrator edits the job. Build logic and code lived in different places and fell out of step.

A handful of small ideas that make everything else easy.

Source control server

The place where code is stored, for example GitHub, GitLab or Bitbucket. Jenkins asks it questions such as “which branches exist?” and “what changed?”

Branch source

The Multibranch Pipeline’s connection to a repository. It holds the address of the repository, the credentials to access it, and rules about what to discover. A job can have one or several branch sources.

Behaviors

Small switches attached to a branch source that decide what to discover: branches, pull requests from the same repository, pull requests from forks, and tags. They also decide filters and how pull requests are built.

Indexing, or scanning

The act of asking the source control server for its current list of branches and pull requests, comparing it with Jenkins’ list, and creating, updating or removing child jobs. Jenkins calls this branch indexing, and shows a log of each run.

Child job

The individual pipeline job created for one branch, pull request or tag. It has its own build history, its own workspace and its own page.

Orphaned item

A child job whose branch has disappeared. Jenkins keeps it for a while according to a rule, then removes it.

Which parts of a Jenkins setup work together.

A Multibranch Pipeline is made of a few cooperating pieces. There is the job itself, which behaves like a folder. There are branch source plugins that know how to talk to particular code hosting services. And there are the child jobs, which run on agents like any other pipeline.

flowchart LR
    DEV["Developers push branches and open pull requests"] --> SCM["Source Control Server"]
    SCM -->|"webhook event"| CTRL["Jenkins Controller"]
    CTRL --> MB["Multibranch Pipeline job"]
    MB --> BS["Branch Source Plugin"]
    BS -->|"list branches and pull requests"| SCM
    MB --> J1["Child job: main"]
    MB --> J2["Child job: feature login"]
    MB --> J3["Child job: PR 42"]
    J1 --> AG["Build Agents"]
    J2 --> AG
    J3 --> AG
    AG --> REP["Reports and Artifacts"]
    AG -->|"status back"| SCM

Read the diagram from left to right. Developers push code, and the source control server sends a webhook, an automatic message telling Jenkins that something happened. The controller wakes the Multibranch job, which uses the branch source plugin to list the current branches and pull requests. Child jobs appear or update. Each child job runs on an agent, produces reports and artifacts, and sends its status back to the code host, so the pull request page shows a green tick or a red cross.

The main sections you fill in when creating the job.

You create a Multibranch Pipeline by choosing that job type in Jenkins and giving it a name. The configuration page is short compared with older job types, because most of the real logic lives in the Jenkinsfile. The important sections, in the order they usually appear, are these.

Deciding what Jenkins should discover.

Kinds of branch sources

Plugins exist for the popular code hosts, such as GitHub, Bitbucket, GitLab and Gitea. There is also a generic Git source that works with any Git server but knows less about pull requests. Choosing the specific plugin for your host gives you richer features, especially pull request discovery and status reporting.

Behaviors in detail

Why filters matter

Without filters, every personal experiment branch becomes a job. In a large team that can mean hundreds of jobs, each consuming build time, disk space and controller memory. A simple naming convention, such as building only main, develop, release branches and pull requests, keeps the system calm and the queue short.

What Jenkins does during a branch indexing run.

flowchart TD
    T["Trigger: webhook, timer or manual scan"] --> L["Ask code host for branches, pull requests, tags"]
    L --> F["Apply behaviors and filters"]
    F --> C{"Has Jenkinsfile at script path?"}
    C -->|"No"| S["Skip this item"]
    C -->|"Yes"| K{"Child job exists?"}
    K -->|"No"| N["Create child job and build it"]
    K -->|"Yes"| U{"Revision changed?"}
    U -->|"Yes"| B["Trigger a build"]
    U -->|"No"| I["Leave as is"]
    F --> O["Compare with existing children"]
    O --> R["Mark missing ones as orphaned"]

An important consequence follows: a branch without a Jenkinsfile is simply invisible to Jenkins. That is by design. It lets a repository hold old branches, documentation branches or experiments that never need a build, without any special configuration.

Two ways to make Jenkins notice new work.

Jenkins does not magically know when someone pushes code. Something has to tell it, or it has to ask. There are two ways, and good setups use both.

Webhooks first, timer as a safety net

The best practice is to rely on webhooks for speed and keep a slow periodic scan, often once a day, as a safety net. If a webhook is lost because of a network glitch or a restart, the next scan catches up. Polling every minute instead of using webhooks is a classic mistake: it wastes request quota, loads the controller, and still reacts slower.

flowchart LR
    P["Push or pull request event"] --> H["Code host sends webhook"]
    H --> J["Jenkins receives event"]
    J --> Q["Targeted scan of that branch only"]
    Q --> B["Build starts within seconds"]
    T["Daily safety-net timer"] --> F["Full scan of whole repository"]
    F --> B

How Jenkins organizes everything it creates.

flowchart TD
    ORG["Jenkins root"] --> MB["Multibranch job: booking-service"]
    MB --> M["main"]
    MB --> D["develop"]
    MB --> R["release-4.12"]
    MB --> FL["feature login page"]
    MB --> P1["PR-41"]
    MB --> P2["PR-42"]
    M --> MH["Own build history and workspace"]
    P2 --> PH["Own build history and workspace"]

Names

Branches become child jobs named after the branch. Because a slash is used in web addresses, a branch called feature/login appears with its slash encoded, so the address contains a percent-two-F sequence. This surprises people who build addresses by hand. Pull requests appear as PR- followed by their number.

History

Each child keeps its own build numbers, logs, test results and artifacts. Build number 1 of one branch has nothing to do with build number 1 of another. That separation is useful: a failing feature branch never pollutes the record of the main branch.

Workspaces

Every child job gets its own workspace on the agent, named from the job path. Long branch names can create very long folder paths, which cause problems on some operating systems. Jenkins shortens the path with a hash when needed, but very long names remain a risk on machines with strict path limits.

The variables and conditions that let one file behave differently per branch.

The same Jenkinsfile is usually shared by all branches, because it lives in the code and branches are copies of the code. To behave differently, the pipeline reads information that Jenkins provides about the current build.

The when conditions

Declarative pipelines have a when directive that decides whether a stage runs. Three conditions are made for multibranch work: branch, which matches a branch name or pattern; changeRequest, which is true only for pull requests and can be narrowed by target or author; and tag, which matches tag names. Using them, one file can say “run the deploy stage only on main,” “run the preview stage only on pull requests,” and “run the release stage only on tags.”

Checking out the right code

Inside a multibranch child, a special variable named scm describes exactly which branch and revision Jenkins is building. A checkout step that uses it always fetches the right code. Writing a checkout with a hard-coded branch name is a frequent mistake that makes every child job build the same branch.

The most valuable and most delicate part of multibranch builds.

What Jenkins actually builds

A pull request has two interesting pieces of code: the changed branch as it is, and what the target branch would look like after the merge. Building the first tells you whether the change works alone. Building the second tells you whether it works together with the latest main. Branch source plugins let you choose, commonly offering to build the merged result, the pull request head alone, or both as separate jobs.

Pull requests from forks

A fork is a personal copy of a repository, often owned by someone outside your team. Their pull requests contain code you have not reviewed, and possibly a modified Jenkinsfile. Running that automatically with access to your servers and secrets would be dangerous.

Branch source plugins therefore offer a trust policy, which decides whose pull requests are treated as trusted. Policies range from trusting nobody, to trusting only people with write access, to trusting everyone. For untrusted pull requests, the safe approach is to use the Jenkinsfile from the target branch, not from the pull request, so the outsider cannot change the build recipe. Some setups also refuse to build untrusted requests until a maintainer approves them.

flowchart TD
    PR["Pull request opened"] --> W{"From the same repository?"}
    W -->|"Yes"| TR["Trusted: use PR Jenkinsfile"]
    W -->|"No, from a fork"| TP{"Author trusted by policy?"}
    TP -->|"Yes"| TR
    TP -->|"No"| UT["Untrusted: use target branch Jenkinsfile"]
    UT --> NS["No secrets, limited stages, or wait for approval"]
    TR --> FULL["Full pipeline with normal access"]
    FULL --> ST["Status shown on the pull request"]
    NS --> ST

Building versions that have been officially labeled.

A tag is a permanent label on one exact point in the history, usually a version such as v4.12.0. Unlike branches, tags do not move. That makes them perfect for releases: the code labeled v4.12.0 is the same today and in three years.

When you enable tag discovery, Jenkins creates a child job for each tag it finds. Inside that job the variable TAG_NAME holds the label, and the tag condition lets a stage run only for tag builds. A common design is that the normal pipeline builds and tests everything, while a release stage that publishes packages runs only when the build is for a tag whose name matches a version pattern.

What happens when branches are merged and deleted.

Branches are short-lived. After a pull request is merged, the branch is usually deleted. The next scan notices that the branch is gone and marks its child job as orphaned. Jenkins then applies the orphaned item strategy you chose.

Why to keep them briefly

Keeping orphans for a few days lets people look at the logs of a build from a branch that was just merged, for example to investigate a strange failure after the fact. Removing them quickly reduces clutter and disk use. A short retention with a maximum count is the usual balance.

Two levels of cleanup

The orphaned item strategy removes whole child jobs. A separate setting inside each Jenkinsfile, the build discarder, removes old builds within a job, keeping only a chosen number. Use both: the first stops job clutter, the second stops history from growing endlessly inside long-lived branches such as main.

Scanning a whole organization instead of a single repository.

A Multibranch Pipeline watches one repository. If you have fifty microservices in fifty repositories, creating fifty Multibranch jobs is exactly the chore we wanted to avoid. An organization folder solves this. It scans all repositories belonging to an organization or user on the code host, and for every repository containing a Jenkinsfile it creates a Multibranch Pipeline automatically. It is a Multibranch job for the entire organization.

flowchart TD
    OF["Organization folder: acme-company"] --> R1["Repository: booking-service"]
    OF --> R2["Repository: payments-service"]
    OF --> R3["Repository: notification-service"]
    R1 --> B1["main"]
    R1 --> B2["PR-12"]
    R2 --> B3["main"]
    R2 --> B4["feature refund"]
    R3 --> B5["main"]

Two scanning levels

There are now two kinds of scan. The organization scan discovers repositories. Each repository’s own scan discovers branches and pull requests. A new repository with a Jenkinsfile appears in Jenkins minutes after it is created, with no one visiting the Jenkins page at all.

When to choose it

Using branch names to decide what each build does.

The greatest strength of multibranch pipelines is that one Jenkinsfile can deliver different results depending on where the code came from. A popular convention maps branches to environments.

flowchart LR
    C["Code pushed"] --> Q{"Build type"}
    Q -->|"Pull request"| A["Build and unit tests"]
    A --> PV["Preview environment"]
    Q -->|"develop"| D["Build, full tests, package"]
    D --> ST["Staging"]
    Q -->|"main"| M["Build, full tests, scan"]
    M --> AP["Approval gate"]
    AP --> PR["Production"]
    Q -->|"tag"| T["Publish release packages"]

Preview environments deserve a special mention. Creating a short-lived copy of the application for each pull request lets reviewers click through the change before merging. The catch is cleanup. Tear the environment down when the pull request closes or when the job is removed, or the bills will keep growing.

A subtle behavior that surprises almost everyone once.

A Jenkinsfile can declare properties such as build parameters, timer-based triggers and options like the build discarder. These are registered on the child job when a build of that branch runs. Before the first build, Jenkins does not know about them.

What this means in practice

• A brand-new branch with a parameter in its Jenkinsfile will build once with default values, because the parameter form does not exist yet. After that first run the form appears.
• A timer-based trigger declared in a Jenkinsfile starts working only after the branch has built at least once.
• If you change a parameter definition, the new form appears only after the next build.

Who can see what, and which secrets each build can use.

Folder-scoped credentials

A Multibranch job behaves like a folder, and folders can hold their own credentials. Storing a deployment key in the folder means only jobs inside it can use it, rather than every job on the server. This limits the damage if one job is misused.

Permissions

Permissions set on a folder flow down to its children unless changed. Teams commonly give developers permission to view and build, give release managers permission to approve deployments, and reserve configuration rights for a small group of administrators. Each child job inherits this, so a new branch is covered instantly without any extra steps.

Because every branch can carry its own build recipe, the trust model matters.

Pipeline as code is powerful precisely because the code controls the build. It also means that whoever can push a branch can change what the build does. Security therefore rests on three ideas: know who can push, limit what unreviewed code can reach, and keep secrets away from untrusted builds.

Also remember that the branch names and pull request titles are text controlled by outsiders. Never paste them unchecked into commands. A branch name can contain characters that confuse shell commands, so treat these values as untrusted input and validate them before use.

How to know that your multibranch setup is healthy.

The scan log

Every indexing run writes a log accessible from the Multibranch job page. It lists each branch and pull request found, whether it has a Jenkinsfile, and what Jenkins decided to do. This is the first place to look when a branch does not appear, and a beginner’s best friend for understanding what the system is doing.

Metrics worth watching

Monitoring plugins can expose these numbers to systems such as Prometheus, and dashboards make them visible to the whole team. The code host’s own webhook page also shows recent deliveries and their responses, which quickly reveals connection problems.

What changes when you have hundreds of repositories and thousands of branches.

Every child job is a real Jenkins job with its own record on the controller. A few hundred are no trouble. Many thousands begin to weigh on memory, on the loading time of pages and on scan duration. The main levers are to create fewer jobs, scan less often and make each build lighter.

Those figures are only an illustration, but they show how quickly numbers multiply. Two hundred repositories with fifteen active branches each produce three thousand child jobs. Cutting active branches to five per repository by filtering and quick cleanup cuts the load by two thirds.

Reliable ways of arranging multibranch setups.

Habits that look fine at first and hurt later.

A checklist to apply to any Multibranch setup today.

Mistakes people make when they are new

Forgetting the Jenkinsfile. A branch without the pipeline file at the expected path is invisible. New teams often wonder why a branch never appears, when the answer is simply that the file is missing or named differently.

Wrong script path. If the Jenkinsfile lives in a subfolder, the script path must say so. Otherwise every branch is skipped.

Expecting instant pull request builds without webhooks. Without a working webhook, builds appear only at the next scan, which can be hours.

Ignoring the first-run effect. Parameters and triggers appear only after a branch has built once.

Not thinking about forks. Public repositories receive pull requests from strangers. Decide your trust policy before opening the door.

Building the same code twice. If a branch has an open pull request and both are discovered, the same code can build twice. Choose discovery options that avoid duplicates, unless you truly want both results.

An honest look at what Multibranch Pipelines do well and where they strain.

Trade-offs to weigh

There is no universally right answer. The right settings depend on your team size, how fast branches appear, and how much risk you accept. Choose on purpose and write down why.

How the ideas look in the kinds of organizations that run Jenkins at scale.

Where the Multibranch Pipeline fits among its relatives.

Follow one imaginary team through a working day.

A team owns a booking service. Their organization folder scans the company’s repositories. The booking repository has a Jenkinsfile that uses a shared library. Pull requests are discovered from the same repository and from forks with a strict trust policy. Branches are filtered to main, develop and release names, and old jobs are removed after two weeks.

Symptoms, likely causes and calm fixes.

A calm debugging routine

1. Open the scan log of the Multibranch job and find the branch in question.
2. Read the decision Jenkins made: no Jenkinsfile, filtered, or created.
3. Check the code host’s webhook page if the trouble is timing.
4. Read the child job’s console log to see which revision was built.
5. Change one thing at a time and rescan.

Every important word in this guide in one place.

Short answers to the questions that come up most often.

The whole story in a few lines.

A Multibranch Pipeline is a manager job. You connect it to a repository once, and it discovers branches, pull requests and tags that have a Jenkinsfile, creating and removing child jobs automatically. Each child runs its own pipeline and reports back to the code host. Organization folders extend the same idea to many repositories. Used well, with webhooks, filters, trust policies, cleanup rules and branch-aware pipelines, it gives fast feedback with almost no manual upkeep. Used carelessly, it multiplies jobs, exhausts request limits and exposes secrets to strangers.