Guide: Setting Up a Declarative Jenkins Pipeline for Maven Build and Test

Desired Outcome

Create a Jenkins job that automatically builds a Maven‑based Java project, runs unit tests, and reports results using a Declarative Pipeline defined in a Jenkinsfile. The pipeline should show distinct stages for checkout, build, test, and post‑build actions in the Jenkins UI (Blue Ocean or Stage View).

Prerequisites

• Jenkins 2.300+ installed and accessible with administrative rights to create jobs.
• A source‑code repository (Git) containing a Maven project with a pom.xml at its root.
• Docker available on the Jenkins agents (or a cloud‑based agent template) to run the maven:3.9-eclipse-temurin-17 image.
• Jenkins Credentials Provider configured with a username/password or SSH key named git-credentials for repository access.
• Basic familiarity with creating a Multibranch Pipeline job in Jenkins.

Procedure

1. Add a Jenkinsfile to the repository

   Place the following Declarative Pipeline at the root of the repo (adjust YOUR_IMAGE_TAG if you need a specific Maven version).

   pipeline {
       agent { docker { image 'maven:3.9-eclipse-temurin-17' args '-v $HOME/.m2:/root/.m2' } }
       parameters {
         string(name: 'BUILD_TAG', defaultValue: 'latest', description: 'Tag for the build artifact')
       }
       stages {
         stage('Checkout') {
           steps {
             checkout([
               $class: 'GitSCM',
               branches: [[name: '*/main']],
               doGenerateSubmoduleConfigurations: false,
               submoduleCfg: [],
               userRemoteConfigs: [[
                 credentialsId: 'git-credentials',
                 url: 'https://github.com/example/my‑maven‑app.git'
               ]]
             ])
           }
         }
         stage('Build') {
           steps {
             sh "mvn -B clean package -DskipTests"
           }
         }
         stage('Test') {
           steps {
             sh "mvn -B test"
           }
         }
       }
       post {
         always {
           cleanWs()
           echo 'Workspace cleaned up.'
         }
         success {
           echo "Build ${env.BUILD_TAG} succeeded."
           mail to: '[contact removed]',
                subject: "Jenkins Build ${env.BUILD_NUMBER} Successful",
                body: "Check the artifacts at ${env.BUILD_URL}artifact/target/"
         }
         failure {
           echo "Build ${env.BUILD_TAG} failed."
           mail to: '[contact removed]',
                subject: "Jenkins Build ${env.BUILD_NUMBER} FAILED",
                body: "See console output: ${env.BUILD_URL}console"
         }
       }
     }
   

   Commit and push the file:

   git add Jenkinsfile
    git commit -m "Add Declarative Jenkins Pipeline"
    git push origin main
   

2. Create a Multibranch Pipeline job in Jenkins
   1. Log in to Jenkins as an administrator or a user with the Job/Create permission.
   2. Select New Item → Multibranch Pipeline, give it a name (e.g., my-maven-app), and click OK.
   3. Under Branch Sources, choose Git, enter the repository URL, and select the credentials git-credentials.
   4. Leave the default Scan Repository Triggers (periodic scan) or configure a webhook for immediate triggering.
   5. Save the job. Jenkins will scan the repository, detect the Jenkinsfile, and create a pipeline branch for the main branch.
3. Run the pipeline

   Either wait for the automatic scan or click Build Now on the newly created branch.

Expected Checks

• In the Jenkins UI, open the pipeline run and verify that the Stage View (or Blue Ocean) shows four distinct blocks: Checkout, Build, Test, and Post with appropriate timing.
• Check the Console Output for each stage:
  • The docker agent line should indicate successful container startup.
  • The mvn commands should exit with code 0 for Build and Test stages (unless a test fails, which is expected to be caught).
  • The post section should print the always message and, depending on outcome, either the success or failure block.
• If tests fail, the pipeline should stop after the Test stage, trigger the failure block, and send the configured email notification.
• After the run finishes, the workspace should be clean (no leftover files) as verified by the cleanWs() step in the always block.

Recovery Options

Creating the Jenkinsfile and the Multibranch Pipeline job adds configuration state to Jenkins. If you need to revert:

1. Disable the job: open the job configuration, check Disable this project, and save. This stops further builds while preserving history.
2. To completely remove the job and its build history, delete the job from the Jenkins dashboard (Actions → Delete). This removes the job configuration but does not affect the source repository.
3. If the pipeline was running with a Docker agent and the container failed to start, check the node’s Docker daemon logs and ensure the maven image is pullable. Re‑run after fixing the image pull issue.