Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 44 ยท Projects

Project: A Jenkins Multibranch Pipeline

Build a Jenkins multibranch pipeline step by step: a Jenkinsfile with build, test and package stages, branch rules, parallel checks and post notifications.

A Jenkins multibranch pipeline is the setup most teams actually use: you point Jenkins at a repository, and it discovers every branch and pull request that contains a Jenkinsfile. Each branch gets its own job, created automatically, and removed when the branch is deleted. The pipeline definition lives in the repository, so changing the build is a code change that goes through review like any other.

In this project you will write a complete Jenkinsfile for a small Java web service. It builds, tests in parallel, packages, runs different stages depending on the branch, and reports the result. Jenkins itself cannot run on this site, so the Groovy below is read-only and the commands are not executed. The runnable part is a stand-in: a Node.js program that decides which stages a given branch would run, which is the logic the when directives implement. Before you start, make sure you are comfortable with The Declarative Jenkinsfile and Agents, Docker Agents and Credentials.

What we are building

The requirements, in the order a reviewer would state them:

  • Every branch and pull request: compile and run the unit tests.
  • Pull requests: also run static analysis, but never deploy.
  • The main branch: build a package, archive it, and deploy it to a staging server.
  • Tags that look like v1.2.3: build a release package.
  • Always: publish test reports and tell the team when the build breaks or recovers.
flowchart LR
  C["Checkout"] --> B["Build"]
  B --> Q["Checks (parallel)<br/>unit tests, static analysis"]
  Q --> P["Package"]
  P --> D["Deploy to staging<br/>main only"]

Stages run left to right; the parallel block fans out and rejoins, and Deploy is conditional.

Step 1: the skeleton

Declarative syntax gives the pipeline a fixed structure, so it is easy to read and Jenkins can validate it before running anything:

GROOVY
pipeline {
  agent none

  options {
    timeout(time: 30, unit: 'MINUTES')
    buildDiscarder(logRotator(numToKeepStr: '20'))
    disableConcurrentBuilds(abortPrevious: true)
    timestamps()
  }

  environment {
    APP_NAME = 'orders-service'
  }

  stages {
    // stages go here
  }
}

agent none at the top means no stage gets a machine until it asks for one. That matters for cost: a stage waiting for human input should not hold an executor. timeout stops a stuck build, buildDiscarder keeps only the last 20 builds per branch (multibranch projects create many jobs, so retention matters), and disableConcurrentBuilds(abortPrevious: true) cancels an older build on the same branch when a newer commit arrives. The timestamps() option needs the Timestamper plugin, which most installations have.

Step 2: build with a Docker agent

Give each stage that needs tools a clean, repeatable environment. A Docker agent starts a container from an image for the stage:

GROOVY
    stage('Build') {
      agent {
        docker { image 'maven:3.9-eclipse-temurin-21' }
      }
      steps {
        sh 'mvn -B -ntp clean compile'
        stash name: 'workspace', includes: 'target/**,pom.xml,src/**'
      }
    }

Because later stages may run on different agents, stash saves the files that later stages need and unstash brings them back. Stash is meant for modest amounts of data inside one build; for larger files or files you want to keep after the build ends, use archiveArtifacts. The -B flag makes Maven print batch-style logs without colors, and -ntp hides download progress that would flood the log.

Step 3: parallel checks

Unit tests and static analysis are independent, so run them side by side. A parallel block inside a stage runs each branch on its own executor:

GROOVY
    stage('Checks') {
      parallel {
        stage('Unit tests') {
          agent {
            docker { image 'maven:3.9-eclipse-temurin-21' }
          }
          steps {
            unstash 'workspace'
            sh 'mvn -B -ntp test'
          }
          post {
            always {
              junit 'target/surefire-reports/*.xml'
            }
          }
        }
        stage('Static analysis') {
          when { changeRequest() }
          agent {
            docker { image 'maven:3.9-eclipse-temurin-21' }
          }
          steps {
            unstash 'workspace'
            sh 'mvn -B -ntp spotbugs:check'
          }
        }
      }
    }

Two details are important. The junit step sits in post { always { ... } } so test results are published even when a test fails; that is exactly when you want to read them. And when { changeRequest() } makes the analysis stage run only for pull requests, using the metadata that the multibranch job gets from your source-control provider. In a parallel block, if one branch fails the others still finish unless you set failFast true on the parent stage; for slow checks, fast failure saves time.

Step 4: package, with branch rules

Packaging runs for main and for release tags, not for every feature branch:

GROOVY
    stage('Package') {
      when {
        beforeAgent true
        anyOf {
          branch 'main'
          buildingTag()
        }
      }
      agent {
        docker { image 'maven:3.9-eclipse-temurin-21' }
      }
      steps {
        unstash 'workspace'
        sh 'mvn -B -ntp -DskipTests package'
        archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
      }
    }

By default Jenkins allocates a stage's agent before it evaluates when. beforeAgent true reverses that, which avoids starting a container just to find out the stage will be skipped. (The static analysis stage above would benefit from it too.) Fingerprinting records the checksum of each archived file, so you can later trace which build produced a given jar.

Tag builds need one extra setting. By default a multibranch job does not discover tags; you enable the tag discovery behavior in the branch source configuration. With it on, a tag v1.2.3 becomes its own job, and buildingTag() is true inside it. You can match the name with tag pattern: 'v\\d+\\.\\d+\\.\\d+', comparator: 'REGEXP'.

Step 5: deploy to staging from main only

GROOVY
    stage('Deploy to staging') {
      when {
        beforeAgent true
        branch 'main'
      }
      agent { label 'deploy' }
      environment {
        DEPLOY_KEY = credentials('staging-ssh-key')
      }
      steps {
        copyArtifacts projectName: env.JOB_NAME, selector: specific(env.BUILD_NUMBER)
        sh './scripts/deploy.sh staging target/orders-service.jar'
      }
    }

The credentials() helper reads a secret from the Jenkins credentials store and exposes it only inside this stage; Jenkins masks the value if it appears in the console output. The agent label deploy sends the work to a machine that is allowed to reach the staging server, so the build agents themselves never need that access. (copyArtifacts comes from the Copy Artifact plugin. If you prefer not to add a plugin, unstash works when the stash was created earlier in the same run.)

Step 6: post conditions and notifications

The post section at the end of the pipeline reacts to the build result:

GROOVY
  post {
    failure {
      mail to: '[email protected]',
           subject: "FAILED: ${env.JOB_NAME} #${env.BUILD_NUMBER}",
           body: "See ${env.BUILD_URL}"
    }
    fixed {
      echo 'The build is green again after a failure.'
    }
    cleanup {
      echo 'Runs last, whatever happened.'
    }
  }

failure runs when the build fails, fixed runs when a build succeeds after a failed one (so people hear about recoveries), and cleanup runs after all other post conditions. Because the top-level agent is none, steps that need a workspace, such as deleteDir(), would need a node or agent wrapper. The mail step requires a mail server configured under Manage Jenkins. For Slack or Teams, install that plugin and use its step in the same place; its exact name depends on the plugin version, so check the plugin page.

Finally, configure the job itself: create a Multibranch Pipeline item, add your Git host as a branch source with the right credentials, and set the script path to Jenkinsfile. Add a webhook from the Git host to Jenkins so a push triggers a scan right away; otherwise rely on periodic scanning, which is slower and puts more load on both systems.

Stand-in: which stages run on which branch

The Groovy when conditions are small rules about the branch name, pull request status and tag. This Node.js program models that decision for several kinds of builds. It is not Jenkins; it only reproduces the rules above so you can reason about them and see the output for each case.

Node.js Branch-aware stage selection

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that the release tag runs Package but not Deploy staging. If you wanted tags to deploy to production, you would add a separate stage with its own when { buildingTag() } and an approval step rather than overloading the staging stage.

Stand-in: post conditions and the build result

Post conditions depend on the result of this build and on the previous one. The second model reproduces that logic so you can see when failure, fixed and cleanup fire.

Node.js Which post conditions fire?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A repeated failure sends a failure mail every time, which can be noisy. Many teams alert on regression or failure only the first time, and use fixed for the good news.

Review checklist

  • The Jenkinsfile is in the repository root, and pull requests that change it are reviewed.
  • No secrets appear in the file; everything sensitive uses the credentials store.
  • Every stage that allocates an agent has a time budget, either per stage or through the global timeout.
  • junit and archiveArtifacts are in post or run before anything that can abort the build.
  • The deploy stage is guarded by branch, agent label and credentials.
  • Old builds are discarded, and the job is not triggered by polling if webhooks are possible.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a multibranch pipeline job do?

    Jenkins scans the repository, finds branches and pull requests containing a Jenkinsfile, and manages a job for each one.
  2. 2. Why is junit placed in post { always { ... } }?

    A failed test makes the steps block stop. The always condition still runs, so the report you most need is available.
  3. 3. Which directive runs a stage only for pull requests?

    changeRequest() is true when the build comes from a pull request or merge request discovered by the multibranch job.
  4. 4. What does the fixed post condition mean?

    fixed fires when the current build is successful and the previous one was not. It is a good place for a recovery message.
  5. 5. Why use agent none at the top level and agents per stage?

    Agents are allocated only for stages that need them, so executors are not tied up by waiting or skipped work.

Summary

  • A multibranch pipeline discovers branches and pull requests and builds each from the Jenkinsfile in that branch.
  • when directives (branch, changeRequest, buildingTag, anyOf) choose stages per build; add beforeAgent true to avoid allocating agents for skipped stages.
  • parallel runs independent checks together; publish reports from post { always }.
  • Use stash/unstash for files within a run and archiveArtifacts for files to keep.
  • credentials() and agent labels limit who can deploy and where secrets are visible.
  • failure, fixed and cleanup handle notifications and last-step tidying.
  • The Groovy is read-only here; the Node.js programs only model the rules.

Next: Project: A GitLab Pipeline with Review Apps