Jenkins Backup, Restore, and Maintenance

A Jenkins server holds months or years of build history, pipeline configurations, credentials, and plugin settings. Losing that data means rebuilding everything from scratch. Regular backups and a tested restore process protect your team from that scenario.

Think of Jenkins backup as insurance for your car. You hope you never need it. But when something goes wrong — a disk failure, an accidental deletion, a bad upgrade — you are glad you have it.

What to Back Up

Everything Jenkins needs lives in the JENKINS_HOME directory. Back up this entire directory and you can restore Jenkins completely.

JENKINS_HOME contents and importance:

  /var/lib/jenkins/
  ├── jobs/                  ← ALL job configs and build history  ★★★
  │   ├── my-job/
  │   │   ├── config.xml     ← Job configuration
  │   │   └── builds/        ← Build history and logs
  ├── plugins/               ← Installed plugins (.jpi files)     ★★
  ├── secrets/               ← Encrypted credentials              ★★★
  ├── credentials.xml        ← Credential definitions             ★★★
  ├── config.xml             ← Main Jenkins configuration         ★★★
  ├── users/                 ← User accounts and API tokens       ★★
  ├── nodes/                 ← Agent node configurations          ★★
  └── workspace/             ← Temp build files (no backup needed)

Priority:
  ★★★ Must back up — cannot recreate easily
  ★★  Should back up — saves significant setup time
  ✗   Skip — large, recreatable, or auto-downloaded

Backup Methods

Method 1: File System Backup (Simplest)

Copy the JENKINS_HOME directory to another location. Run this when Jenkins is idle or use the ThinBackup plugin to handle it safely while Jenkins is running.

Manual backup command (Linux):
  # Stop Jenkins first for a consistent backup
  sudo systemctl stop jenkins

  # Create timestamped backup archive
  sudo tar -czf /backups/jenkins-$(date +%Y%m%d-%H%M).tar.gz \
    /var/lib/jenkins \
    --exclude=/var/lib/jenkins/workspace \
    --exclude=/var/lib/jenkins/cache

  # Restart Jenkins
  sudo systemctl start jenkins

Restore from backup:
  sudo systemctl stop jenkins
  sudo tar -xzf /backups/jenkins-20240510-0200.tar.gz -C /
  sudo systemctl start jenkins

Method 2: ThinBackup Plugin

ThinBackup runs backups automatically on a schedule while Jenkins is running. It supports full backups and incremental backups (only changed files since the last full backup).

Install: ThinBackup plugin
Configure: Manage Jenkins → ThinBackup → Settings

  Backup directory: /backups/jenkins
  Full backup schedule:  H 2 * * 0   (Every Sunday at 2 AM)
  Diff backup schedule:  H 2 * * 1-6 (Mon–Sat at 2 AM, incremental)
  Max number of backups: 30
  ✓ Back up plugins archives
  ✓ Back up next build number file

Run a manual backup:
  Manage Jenkins → ThinBackup → Backup Now

Restore:
  Manage Jenkins → ThinBackup → Restore
  Select backup date from the dropdown
  Click Restore

ThinBackup backup types:

  Full backup:
    - Copies all configuration files
    - Larger file size
    - Self-contained — can restore from this alone
    - Run weekly

  Differential (diff) backup:
    - Copies only files changed since last full backup
    - Much smaller file size
    - Requires the last full backup to restore
    - Run daily

Method 3: Git-Based Configuration Backup (Job DSL / JCasC)

Jenkins Configuration as Code (JCasC) stores your entire Jenkins configuration in a YAML file. Store that file in Git. Rebuilding Jenkins from scratch takes minutes — pull the YAML and apply it.

Install: Configuration as Code plugin
Configure: Manage Jenkins → Configuration as Code

Example jenkins.yaml:
  jenkins:
    systemMessage: "Production Jenkins Server"
    numExecutors: 0
    securityRealm:
      ldap:
        server: "ldap://ldap.mycompany.com"
        rootDN: "dc=mycompany,dc=com"
    authorizationStrategy:
      roleBased:
        roles:
          global:
            - name: "admin"
              permissions:
                - "Overall/Administer"
              entries:
                - user: "diana"

Store jenkins.yaml in Git:
  git add jenkins.yaml
  git commit -m "Update Jenkins configuration"
  git push

Restore/rebuild Jenkins:
  1. Install Jenkins fresh
  2. Install JCasC plugin
  3. Point it to jenkins.yaml in Git
  4. Apply → Jenkins configuration restored in minutes

Scheduled Backup with a Jenkins Job

Create a Jenkins job that runs a backup script on a schedule. This keeps the backup process visible, logged, and manageable from the Jenkins interface.

Freestyle job: jenkins-backup
  Build periodically: H 3 * * *   (every night at 3 AM)

  Build step (Execute shell):
    BACKUP_DIR="/backups/jenkins"
    TIMESTAMP=$(date +%Y%m%d-%H%M%S)
    BACKUP_FILE="${BACKUP_DIR}/jenkins-backup-${TIMESTAMP}.tar.gz"

    mkdir -p "${BACKUP_DIR}"

    tar -czf "${BACKUP_FILE}" \
      /var/lib/jenkins/jobs \
      /var/lib/jenkins/config.xml \
      /var/lib/jenkins/credentials.xml \
      /var/lib/jenkins/secrets \
      /var/lib/jenkins/users \
      /var/lib/jenkins/nodes

    # Keep only 14 most recent backups
    ls -t "${BACKUP_DIR}"/jenkins-backup-*.tar.gz | tail -n +15 | xargs rm -f

    echo "Backup complete: ${BACKUP_FILE}"

Jenkins Maintenance Tasks

Updating Jenkins

Check current version:
  Manage Jenkins → System Information → jenkins.version

Update Jenkins (Ubuntu/Debian):
  sudo apt-get update
  sudo apt-get install jenkins

Update Jenkins (WAR file):
  1. Back up JENKINS_HOME first
  2. Download new jenkins.war from jenkins.io
  3. sudo systemctl stop jenkins
  4. sudo cp jenkins.war /usr/share/java/jenkins.war
  5. sudo systemctl start jenkins

Best practice: Test upgrades on a staging Jenkins
instance before upgrading production.

Cleaning Up Disk Space

Jenkins build workspaces and logs accumulate quickly. Run cleanup tasks regularly to prevent disk full errors.

Job-level cleanup:
  In each job configuration:
    General → Discard Old Builds
    Days to keep builds: 30
    Max builds to keep: 50

Pipeline-level cleanup:
  post {
      always {
          cleanWs()   // Delete workspace after every build
      }
  }

Manual workspace cleanup:
  Manage Jenkins → System Information
  OR
  Click any node → Wipe Out Workspace

System-wide cleanup with Workspace Cleanup plugin:
  Manage Jenkins → Workspace Cleanup
  Delete workspaces not accessed in: 7 days

Restarting Jenkins Safely

Safe restart (wait for running builds to finish):
  http://your-jenkins:8080/safeRestart

Immediate restart (cancels running builds — use with caution):
  http://your-jenkins:8080/restart

Prepare for shutdown (queue new builds but finish current):
  http://your-jenkins:8080/quietDown

Cancel quiet down:
  http://your-jenkins:8080/cancelQuietDown

From command line:
  sudo systemctl restart jenkins

Monitoring Jenkins Health

Built-in monitoring endpoints:

  Health check:
    http://your-jenkins:8080/login  → Returns 200 if Jenkins is up

  System information:
    Manage Jenkins → System Information
    Shows all Java properties, environment variables, plugin versions

  Log files:
    Manage Jenkins → System Log
    Add Logger: jenkins   (level: WARNING or INFO)
    Shows real-time log output in the browser

  Disk usage:
    Install "Disk Usage" plugin
    Manage Jenkins → Disk Usage
    Shows disk space per job and workspace

Key Points

  • Back up the entire JENKINS_HOME directory — it contains jobs, credentials, plugins, and configuration.
  • ThinBackup plugin automates scheduled full and incremental backups while Jenkins is running.
  • Jenkins Configuration as Code (JCasC) stores configuration in a YAML file in Git — enables fast rebuilds from scratch.
  • Configure every job to discard old builds, limiting build history to prevent disk space problems.
  • Always back up before upgrading Jenkins or plugins — test upgrades on a staging server first.
Previous lessons
Back to courses
Next lessons

Leave a Comment