Production-Grade Jenkins Pipeline

A complete reference pipeline for learning and mastering Jenkins CI/CD with the following workflow:

Setup Guide: See SETUP_GUIDE.md for step-by-step installation and configuration.

Checkout → Static Analysis → Unit Tests → Build Artifact → Store Artifact →
Docker Build → Push to Registry → Deploy → Smoke/Health Tests → Rollback on Failure

Reference Application

This pipeline uses Spring Petclinic — a well-maintained Spring Boot microservice with:

• Maven build
• Unit tests (excluding integration tests for speed)
• Checkstyle for static analysis
• Spring Boot Actuator (/actuator/health for smoke tests)
• Java 21

---

Quick Start

Prerequisites

Component	RHEL/Alma Linux
Jenkins	2.400+ with Pipeline plugins
Java	21 (Maven wrapper included)
Docker	For container build & deploy
Git	For checkout

Jenkins Plugins

Install via Manage Jenkins → Plugins:

• Pipeline
• Multibranch Pipeline (branch discovery, branch-to-env)
• Pipeline: Stage View (Stage View grid: columns=stages, rows=builds, durations, status)
• Docker Pipeline
• Git
• JUnit
• Copy Artifact
• SSH Agent (required for remote deployment)
• Blue Ocean (optional, modern pipeline UI)
• SonarQube Scanner (optional)
• JaCoCo (optional, for coverage)

Create Multibranch Pipeline Job

1. New Item → Multibranch Pipeline (not "Pipeline")
2. Branch Sources → Add source → Git
3. Repository URL: This repo (or your fork) with Jenkinsfile + scripts
4. Credentials: For private repos
5. Build configuration → Mode: by Jenkinsfile → Script Path: Jenkinsfile
6. Save → Scan Multibranch Pipeline Now

The pipeline discovers branches (main, stage, uat, test, develop, dev) and builds each. Environment is derived from branch.

Branch-to-Environment Mapping

Branch	Deploys to
main / master	prod
stage	stage
uat	uat
test / develop / dev	test
Other branches	test (default)

Push to branch triggers build and deploy to that environment. Prod requires manual approval.

First Run

• Ensure main, stage, uat, test (or develop) exist in your repo
• Set SKIP_SONAR = true if SonarQube is not configured
• Set DEPLOY_METHOD = jar for remote deployment without registry
• Configure webhook for auto-build on push (see SETUP_GUIDE)

---

Multi-Environment Support (test, uat, stage, prod)

Environment is derived from branch (no manual parameter):

Branch	Env	Host (default)	Health URL
main	prod	192.168.31.124	http://192.168.31.124:8080/actuator/health
stage	stage	192.168.31.123	http://192.168.31.123:8080/actuator/health
uat	uat	192.168.31.122	http://192.168.31.122:8080/actuator/health
test/develop/dev	test	192.168.31.121	http://192.168.31.121:8080/actuator/health

Edit the branchToEnv and envConfig maps in the Jenkinsfile to match your setup. Prod deployments require manual approval.

---

Stage View Plugin

The pipeline is Stage View compatible. The Pipeline: Stage View plugin displays a grid on the job page:

• Columns = pipeline stages (Environment Setup, Checkout, Static Code Analysis, etc.)
• Rows = build runs (#63, #62, #61...)
• Cells = status (success/failed/aborted) + duration
• Average stage times = shown below the grid

No code changes needed—the plugin reads stage() blocks from the Declarative Pipeline. Install Pipeline: Stage View and the view appears on the job's main page.

---

Blue Ocean Plugin

The pipeline is Blue Ocean compatible. No special changes are needed—Blue Ocean renders Declarative Pipelines natively.

Blue Ocean features used:

• Stage visualization — Each stage appears as a step in the pipeline view
• input() for prod — Manual approval shows as a "Proceed" / "Abort" button in the UI
• Logs per stage — Click any stage to see its logs

Best practices for Blue Ocean:

• Use clear stage names (already in place)
• Keep stages focused (single responsibility)
• Use input for gates (prod approval)

---

Remote Deployment (Rocky Linux)

The pipeline deploys to the host for the selected environment and runs health checks there. On health failure, it rolls back to the previous build on the same host.

1. Prepare Rocky Linux (192.168.31.121)

# Install Java 21
sudo dnf install -y java-21-openjdk

# Create deploy user with sudo
sudo useradd -m -s /bin/bash deploy
sudo usermod -aG wheel deploy

# Create app directory (in deploy home - no sudo needed)
mkdir -p /home/deploy/petclinic

2. SSH Key-Based Access

On the Jenkins agent (RHEL/Alma):

# Generate key (if needed)
ssh-keygen -t ed25519 -N "" -f ~/.ssh/deploy_key

# Copy to Rocky Linux
ssh-copy-id -i ~/.ssh/deploy_key.pub deploy@192.168.31.121

3. Add Credentials in Jenkins

1. Manage Jenkins → Credentials → Add
2. Kind: SSH Username with private key
3. ID: deploy-ssh-key
4. Username: deploy
5. Private Key: Enter directly — paste the contents of deploy_key (or use From a file on Jenkins agent)

4. Deployment Methods

Method	When to Use
jar	No registry. JAR is copied via SCP and run with java -jar.
docker	With registry: push image, remote pulls. Without: image transferred via docker save/scp/docker load.

For Rocky Linux without a registry, use DEPLOY_METHOD = jar.

5. Health Check & Rollback

• Health URL: http://192.168.31.121:8080/actuator/health
• Health check runs after deploy. If it fails, the pipeline automatically rolls back to the previous build on 192.168.31.121.

---

Pipeline Stages Explained

1. Checkout

• Clones this pipeline repo (Jenkinsfile, scripts)
• Clones Spring Petclinic into app/
• Sets BUILD_TAG = petclinic-{BUILD_NUMBER}-{GIT_SHORT_SHA}

2. Static Code Analysis

• Checkstyle: ./mvnw checkstyle:check (built into Petclinic)
• SonarQube: Optional; use SKIP_SONAR=true to bypass

3. Unit Tests

• Runs ./mvnw test excluding integration tests
• Publishes JUnit XML reports

4. Build Artifact

• ./mvnw clean package -DskipTests
• Produces app/target/spring-petclinic-4.0.0-SNAPSHOT.jar

5. Store Artifact

• Copies JAR to artifacts/
• Archives in Jenkins
• Stashes for potential rollback

6. Docker Image Build

• Multi-stage Dockerfile (Eclipse Temurin 21 JRE)
• Builds image: {REGISTRY}/petclinic:{BUILD_TAG}

7. Push Image to Registry

• Runs when PUSH_TO_REGISTRY=true
• Requires docker-registry-credentials in Jenkins
• Configure DOCKER_REGISTRY in job environment

8. Deploy to Environment

• Uses jenkins/scripts/deploy.sh
• Supports: docker, docker-compose, kubectl
• Set DEPLOY_METHOD env var on agent

9. Smoke / Health Tests

• Polls HEALTH_CHECK_URL until healthy or timeout
• Uses jenkins/scripts/health-check.sh
• Default: http://localhost:8080/actuator/health

10. Rollback on Health Failure

• If health check fails → post { failure } runs
• Uses Copy Artifact to get deployed-image.txt from previous successful build
• Runs rollback.sh with previous image
• Restores last known good deployment

---

Configuration

Environment Variables (Job → Configure → Environment)

Variable	Description	Default
REPO_URL	Application repo	https://github.com/spring-projects/spring-petclinic.git
BRANCH	Branch to build	main
DOCKER_REGISTRY	Container registry host	registry.example.com
APP_NAME	Application name	petclinic
DEPLOY_HOST	Set per-env from branch	test: 192.168.31.121, prod: 192.168.31.124
DEPLOY_USER	SSH user on deploy host	deploy
REMOTE_APP_DIR	App directory on remote	/home/deploy/petclinic
HEALTH_CHECK_URL	Smoke test URL (deploy host)	http://192.168.31.121:8080/actuator/health
HEALTH_CHECK_TIMEOUT	Health check timeout (seconds)	120

Credentials

ID	Use
docker-registry-credentials	Registry login (username/password)
github-credentials	For private app repos (optional)

Testing Rollback

1. Run a successful build (Build #1)
2. Run another build with FORCE_ROLLBACK_TEST = true
3. Health check will fail → rollback deploys Build #1 image

---

Project Structure

pipelines/
├── Jenkinsfile              # Main pipeline
├── README.md
├── SETUP_GUIDE.md           # Complete setup guide
└── jenkins/
    └── scripts/
        ├── deploy.sh        # Deploy (Docker/Compose/K8s)
        ├── health-check.sh  # Smoke test
        └── rollback.sh      # Rollback to previous build

---

RHEL / Alma Linux Notes

Agent Setup

# Install Docker
sudo dnf install -y docker
sudo systemctl enable --now docker
sudo usermod -aG docker jenkins  # or the agent user

# Java 21
sudo dnf install -y java-21-openjdk-devel

Health Check URL

If Jenkins controller and agent are on different hosts:

• Deploy runs on the agent
• Health check runs on the agent
• Use http://localhost:8080/actuator/health when agent and container are on the same host
• For remote agents, use http://<agent-host>:8080/actuator/health

---

Mastery Checklist

• Run full pipeline without SonarQube
• Add SonarQube and interpret quality gates
• Configure Docker registry and push images
• Deploy to dev via Docker
• Trigger rollback with FORCE_ROLLBACK_TEST
• Add Kubernetes deployment
• Add Slack/email notifications on failure
• Implement blue-green or canary deployment

---

License

MIT. Spring Petclinic is Apache 2.0.