Multibranch Pipelines
A multibranch pipeline automatically creates a pipeline for every branch that contains a Jenkinsfile.
A Multibranch Pipeline scans your repository and automatically creates a separate pipeline for each branch that has a Jenkinsfile. New branches appear as new pipelines; deleted branches are removed.
Why it is powerful
- Automatic — no manual job creation per branch.
- Pull requests — with the right plugin it builds PRs too.
- Branch-aware — combine with
when { branch 'main' }so only certain branches deploy.
Setting it up
Create a New Item > Multibranch Pipeline, point it at your repository, and Jenkins scans for branches containing a Jenkinsfile.
Example
// One Jenkinsfile serves every branch.
// The 'when' directive tailors behavior per branch:
pipeline {
agent any
stages {
stage('Build') {
steps { sh 'make build' } // all branches
}
stage('Deploy') {
when { branch 'main' } // only main
steps { sh 'make deploy' }
}
}
}When to use it
- A team creates a multibranch pipeline so every feature branch automatically gets its own CI pipeline the moment a Jenkinsfile is pushed.
- A pull request pipeline runs automatically when a developer opens a PR against main, and the pipeline is deleted when the PR closes.
- An organization uses multibranch to enforce that branches without a Jenkinsfile are never automatically built.
More examples
Jenkinsfile for multibranch discovery
A Jenkinsfile that Jenkins detects during branch scanning to auto-create a pipeline for that branch.
// This file must exist at the repo root for the branch to be discovered
pipeline {
agent any
stages {
stage('Build') { steps { sh 'mvn package' } }
stage('Test') { steps { sh 'mvn test' } }
}
}Branch filter in multibranch config
Configures a multibranch pipeline via Job DSL to discover only main, feature/, and release/ branches.
// In Jenkins job DSL or JCasC, limit discovered branches:
multibranchPipelineJob('myapp') {
branchSources {
github {
id('myapp-github')
repoOwner('org')
repository('myapp')
includes('main feature/* release/*')
}
}
}PR-only when condition
Uses changeRequest() in a when condition to run extra PR-specific checks only on pull request builds.
stage('PR Checks') {
when {
changeRequest()
}
steps {
sh 'npm run lint && npm test'
sh 'danger ci' // comment on the PR
}
}
Discussion