Jenkins Multibranch Pipelines and GitHub Integration

Multibranch Pipeline is a Jenkins job type that automatically discovers every branch in a Git repository and creates a separate pipeline for each one. When you push a new branch, Jenkins creates a pipeline for it automatically. When you delete a branch, Jenkins removes the pipeline.

Think of a Multibranch Pipeline as a self-managing filing system. Instead of you creating a folder for every new project, the system sees a new project arrive and creates the folder automatically. When the project ends and you archive it, the folder disappears.

How Multibranch Pipeline Differs from a Regular Pipeline

Multibranch Pipeline Structure

Repository: https://github.com/myorg/myapp

Branches in repo:
  main
  develop
  feature/login
  feature/payment
  release/2.0

Jenkins Multibranch Pipeline creates:
  myapp (Multibranch Pipeline Job)
    ├── main             ← Separate pipeline
    ├── develop          ← Separate pipeline
    ├── feature/login    ← Separate pipeline
    ├── feature/payment  ← Separate pipeline
    └── release/2.0      ← Separate pipeline

Each branch builds using the Jenkinsfile in THAT branch.

Creating a Multibranch Pipeline

Step 1: Click "New Item" on the Dashboard
Step 2: Enter a name (e.g., "myapp")
Step 3: Select "Multibranch Pipeline"
Step 4: Click "OK"

Step 5: Under "Branch Sources" → click "Add source" → Git or GitHub
Step 6: Set Repository URL and Credentials

Step 7: Under "Behaviors":
  - Discover branches (all, or filter by pattern)
  - Discover pull requests from forks or origin
  - Filter by name (regex or wildcard)

Step 8: Under "Build Configuration":
  Mode: by Jenkinsfile
  Script Path: Jenkinsfile  (default)

Step 9: Set "Scan Multibranch Pipeline Triggers"
  - Periodically if not otherwise run: 1 minute
  OR
  - Use GitHub webhook for instant scanning

Step 10: Save

After saving, Jenkins immediately scans the repository, finds all branches with a Jenkinsfile, and creates a pipeline for each one.

Branch Filtering

In large repositories with hundreds of branches, you do not want to build every branch. Use filter behaviors to build only the branches your team cares about.

Filter examples:

Filter by name (wildcard):
  Include: main develop release/* hotfix/*
  Exclude: test/* throwaway/*

Filter by name (regex):
  Include: ^(main|develop|feature/.+|release/.+)$
  Exclude: ^(wip/.+|poc/.+)$

GitHub Integration with Webhooks

Webhooks make Jenkins react immediately when code is pushed or a pull request is opened — without waiting for Jenkins to poll Git on a schedule.

Setting Up a GitHub Webhook for Multibranch Pipeline

In GitHub repository:
  1. Settings → Webhooks → Add webhook
  2. Payload URL: http://your-jenkins:8080/github-webhook/
  3. Content type: application/json
  4. Events to send:
     ✓ Push events
     ✓ Pull request events
     ✓ Branch or tag creation
     ✓ Branch or tag deletion
  5. Click "Add webhook"

In Jenkins:
  1. Install "GitHub Branch Source" plugin
  2. Configure GitHub Server:
     Manage Jenkins → System → GitHub → Add GitHub Server
     Credentials: GitHub API token (PAT with repo scope)
  3. In the Multibranch Pipeline job:
     Branch Sources → GitHub
     Owner: your-github-org
     Repository: your-repo-name

Pull Request Builds

One of the most powerful features of Multibranch Pipeline is automatic pull request (PR) validation. When a developer opens a PR, Jenkins automatically builds the branch and reports the result directly in GitHub.

Developer workflow:
  1. Creates branch: feature/login
  2. Writes code and pushes commits
     → Jenkins builds feature/login automatically
  3. Opens Pull Request on GitHub
     → Jenkins builds the PR (tests the merged result)
     → GitHub shows build status:
       ✓ CI/Jenkins — All checks passed   ← PR can be merged
       ✗ CI/Jenkins — Build failed        ← PR blocked until fixed
  4. Code reviewer sees test results before reviewing
  5. Merge is blocked if Jenkins reports failure

Diagram: PR validation flow

  Developer opens PR
          |
          v
  GitHub sends webhook → Jenkins
          |
          v
  Jenkins builds feature branch + merges with main
          |
          v
  Tests run
          |
   Pass?       Fail?
     |               |
     v               v
  GitHub PR:       GitHub PR:
  ✓ Checks pass   ✗ Checks failed
  Merge allowed   Merge blocked

The BRANCH_NAME Variable

In Multibranch Pipelines, the BRANCH_NAME environment variable contains the current branch name. Use it to apply different behavior for different branches.

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }

        stage('Deploy to Staging') {
            when {
                branch 'develop'
            }
            steps {
                sh 'deploy.sh staging'
            }
        }

        stage('Deploy to Production') {
            when {
                branch 'main'
            }
            steps {
                input 'Approve production deployment?'
                sh 'deploy.sh production'
            }
        }

        stage('Feature Branch Only') {
            when {
                expression { env.BRANCH_NAME.startsWith('feature/') }
            }
            steps {
                echo "Feature branch build — deployment skipped"
            }
        }
    }
}

GitHub Organization Scan (GitHub Organizations plugin)

Take Multibranch Pipeline further with a GitHub Organization job. It automatically discovers every repository in a GitHub organization and creates Multibranch Pipelines for each one. Every repository with a Jenkinsfile gets an automatic CI/CD pipeline.

GitHub Organization: mycompany

Jenkins discovers:
  mycompany/service-auth      → Multibranch Pipeline
  mycompany/service-api       → Multibranch Pipeline
  mycompany/service-frontend  → Multibranch Pipeline
  mycompany/service-payments  → Multibranch Pipeline

New repository added to org:
  mycompany/service-reports   → Jenkins detects and adds automatically

Key Points

• Multibranch Pipeline automatically discovers branches and creates separate pipeline jobs for each one.
• Each branch uses the Jenkinsfile from that specific branch — branches can have different pipeline behaviors.
• GitHub webhooks trigger immediate builds when code is pushed or pull requests are opened.
• Pull request builds validate code before merging — Jenkins reports pass/fail directly in GitHub.
• Use the BRANCH_NAME variable to apply different steps for feature branches, develop, and main.