Lesson 04 of 8 · Level 2 — Pipelines for teams
Multibranch pipelines and webhooks
Stop creating jobs by hand: multibranch pipelines and organization folders discover every repository, branch, pull request and tag with a Jenkinsfile, webhooks trigger builds instantly, and results report back to the Git server as status checks that can block merging.
From jobs to discovery
Creating one job per branch by hand doesn't scale. Two job types do it for you:
| Type | Discovers |
|---|---|
| Multibranch Pipeline | One repository: every branch, pull request and (optionally) tag that has a Jenkinsfile |
| Organization Folder | A whole GitHub organization / GitLab group / Bitbucket project: every repository with a Jenkinsfile, each as a multibranch pipeline |
Once set up, a new repository with a Jenkinsfile gets CI with no Jenkins configuration at all, which is what makes Jenkins manageable for many teams.
Instead of writing a new register for every new class at school, the office checks the enrolment list every morning and makes a register automatically for each class that has a timetable pinned on the door.
Set up a multibranch pipeline
- Install the branch-source plugin for your server (GitHub Branch Source, GitLab Branch Source, Bitbucket Branch Source).
- New Item → Multibranch Pipeline (or Organization Folder).
- Branch source: repository URL and credentials (a GitHub App is best for GitHub: fine-grained, higher API limits).
- Behaviours: discover branches, discover pull requests (from origin, and from forks with a trust policy), discover tags if you release from tags.
- Script path:
Jenkinsfile. - Orphaned item strategy: discard old branches after N days.
With Configuration as Code (lesson 07) or the Job DSL plugin, this job definition itself lives in Git too.
Webhooks: build on push
Point the Git server's webhook at Jenkins:
| Git server | Webhook URL (examples) |
|---|---|
| GitHub (GitHub plugin / GitHub App) | https://jenkins.example.com/github-webhook/ |
| GitLab (GitLab plugin) | https://jenkins.example.com/project/<job-path> |
| Others / generic | Multibranch Scan Webhook Trigger plugin URL with a token |
Keep a periodic scan (for example once a day) only as a safety net for missed webhooks. If Jenkins isn't reachable from the Git server (internal network), use a webhook relay or let a Git server–side runner trigger builds.
Branch-aware Jenkinsfiles
The same Jenkinsfile behaves differently per build type:
stages {
stage('Test') { steps { sh 'make test' } } // everything
stage('Preview') { when { changeRequest() } steps { sh 'make preview PR=$CHANGE_ID' } }
stage('Publish') { when { branch 'main' } steps { sh 'make push' } }
stage('Release') { when { buildingTag() } steps { sh 'make release VERSION=$TAG_NAME' } }
}
Pull-request builds by default test the PR merged with its target branch, so a green check means "this will work after merging", not just "this branch works on its own".
Status checks back to the Git server
The branch-source plugins report each build as a commit status / check (for example continuous-integration/jenkins/pr-merge). In the repository's branch protection, mark that check as required: a red Jenkins build now blocks the merge button.
Pull requests from forks
A pull request from a fork can change the Jenkinsfile and run arbitrary code on your agents with access to credentials. Configure fork PR trust carefully (for example "from users with admin or write permission"), run untrusted builds on isolated agents without secrets, and never expose deployment credentials to PR builds.
Try it: automatic CI for a repository
- Create a Multibranch Pipeline for a test repository with the branch-aware Jenkinsfile above.
- Add a webhook from the Git server; push to a new branch and watch the job appear and build within seconds.
- Open a pull request; confirm the Preview stage runs and a status check appears on the PR.
- Make the check required in branch protection, push a failing test, and see the merge blocked.
Recap
- Multibranch pipelines and organization folders discover repos, branches, PRs and tags with a Jenkinsfile.
- Webhooks trigger builds instantly; periodic scans only as a fallback.
- Use
when { changeRequest() / branch / buildingTag() }for per-type stages; PR builds test the merge result. - Report status checks and make them required; treat fork PRs as untrusted.
This site is a public version of my personal engineering knowledge hub. It intentionally excludes confidential company information and internal operational details.