Skip to main content
Mapagam

Migrating and Upgrading Jenkins

1. Planning Jenkins Upgrades

Upgrade Planning Steps

  1. Review the CHANGELOG.md or release notes for the target Jenkins version to identify breaking changes, deprecated features, and new capabilities.
  2. Check the Plugin Compatibility matrix to ensure all installed plugins are compatible with the new Jenkins version.
  3. Back up your Jenkins home directory and configuration files to a secure location.
  4. Identify any custom scripts, build jobs, or configurations that may require manual updates due to API changes.
  5. Test the upgrade process in a staging environment before applying it to production.
Step Description Action Required
Review Release Notes Check Jenkins release notes for breaking changes or deprecated features. NEW Review all changes in the latest major version.
Plugin Compatibility Verify that all plugins are compatible with the new Jenkins version. Use Manage Jenkins > Plugin Manager > Advanced to check plugin status.
Backup Strategy Ensure Jenkins home directory and configuration are backed up. Use jenkins_home backup tools or cloud-native solutions.
Staging Environment Test upgrade in a non-production environment. Set up a separate Jenkins instance for validation.
Note: Jenkins versions prior to 2.401 are no longer supported and should not be used in production.

Jenkins Upgrade Approaches

  • Major Upgrade: Moving to a new major version (e.g., 2.300 to 2.400) often requires plugin updates and configuration changes.
  • Minor Upgrade: Moving to a new minor version (e.g., 2.300 to 2.310) usually involves minimal changes and is safer.
  • Rollback Plan: Always have a plan to revert to the previous version if issues arise during or after the upgrade.

2. Backing Up Before Upgrade

Example: Backup Jenkins Home Directory

# Create a compressed archive of Jenkins home directory
tar -czf jenkins-backup-2026-01-01.tar.gz /var/lib/jenkins
Backup Type Description Command/Method
Full Home Directory Complete Jenkins configuration and data tar -czf backup.tar.gz /var/lib/jenkins
Configuration Files Only Jenkins config files (e.g. config.xml) cp -r /var/lib/jenkins/config.xml /backup/
Job Definitions XML files for each job in /var/lib/jenkins/jobs/ tar -czf jobs-backup.tar.gz /var/lib/jenkins/jobs/
Plugin Data Installed plugins and their versions ls /var/lib/jenkins/plugins/
Note: Always verify backup integrity before upgrading.
Warning: Do not upgrade Jenkins without a verified backup.

3. Upgrading Jenkins WAR File

Upgrading the Jenkins WAR file involves replacing the existing WAR file with a newer version. This method is suitable for standalone Jenkins installations.

Step Description Action
1 Backup current Jenkins installation Archive the JENKINS_HOME directory and WAR file.
2 Download new WAR file Obtain the latest stable WAR from Jenkins official download page.
3 Stop Jenkins instance Ensure Jenkins is not running to prevent data corruption.
4 Replace WAR file Copy the new WAR file over the existing one in the Jenkins installation directory.
5 Start Jenkins Launch Jenkins with the updated WAR file.
Note: Ensure that the new WAR file version is compatible with your existing plugins and configurations.

Example: WAR file upgrade process

sudo systemctl stop jenkins
cp jenkins-2.479.war /opt/jenkins/jenkins.war
sudo systemctl start jenkins

4. Upgrading via Package Manager

Upgrading Jenkins using a package manager is the most straightforward method for systems that support it. This approach ensures that dependencies are handled correctly and Jenkins is updated to the latest stable version.

Operating System Package Manager Command Notes
Ubuntu/Debian sudo apt update && sudo apt install jenkins Ensure the Jenkins repository is added to your system. This method installs the latest version available in the repository.
CentOS/RHEL/Fedora sudo yum update jenkins or sudo dnf update jenkins For Fedora, use dnf. For older systems, yum is used. Ensure the Jenkins repository is configured.
macOS (Homebrew) brew upgrade jenkins Homebrew manages Jenkins as a service. The upgrade command updates the package and restarts the service.
Note: Before upgrading, ensure that all plugins are compatible with the new Jenkins version. You can check plugin compatibility in the Manage Plugins section or on the Jenkins plugin site.

Example: Updating Jenkins on Ubuntu

sudo apt update
sudo apt install jenkins
Warning: If Jenkins is running as a service, it will be restarted automatically after the upgrade. Ensure that no critical builds are in progress to avoid data loss or corruption.

5. Upgrading Plugins Before Core

Note: Always upgrade plugins before upgrading Jenkins core to avoid compatibility issues.
Plugin Version Status Notes
Pipeline: Groovy 5.0 NEW Supports latest Groovy syntax
Git 5.0.0 DEPRECATED Use Git Plugin v4.10 or newer

Example: Plugin Upgrade Command

curl -X POST "http://jenkins.example.com/pluginManager/install" \
  -H "Authorization: Basic base64encodedcredentials" \
  -d "pluginId=workflow-aggregator&version=2.39"

Upgrade Workflow

  1. Backup Jenkins configuration and job data
  2. Review plugin compatibility matrix
  3. Upgrade plugins using pluginManager
  4. Restart Jenkins server
  5. Verify plugin functionality post-upgrade

6. Testing Upgrades in Staging

Workflow: Testing Jenkins Upgrades in Staging

  1. Prepare Staging Environment
    • Clone production Jenkins configuration and data
    • Set up identical hardware/software stack (OS, Java version)
  2. Install Target Jenkins Version
    • Download latest stable Jenkins WAR file
    • Run with same JVM options and plugins as production
  3. Restore Production Data
    • Copy Jenkins home directory (config.xml, jobs/, users/)
    • Restore plugin versions and configurations
  4. Run Integration Tests
    • Execute build jobs and verify results match production
    • Validate plugin functionality and compatibility
  5. Monitor Performance
    • Check system resource usage (CPU, memory)
    • Measure job execution times and queue behavior
  6. Validate Security Settings
    • Ensure authentication and authorization work as expected
    • Verify security plugins (e.g., Role-based Matrix Authorization)
Step Description Tools/Commands
Clone Environment Replicate production setup in staging rsync -avz /var/lib/jenkins/ /staging/jenkins/
Install WAR Deploy target Jenkins version java -jar jenkins.war --httpPort=8081
Restore Data Import production configuration and jobs cp -r /backup/jenkins/* /staging/jenkins/
Run Tests Execute build jobs to verify functionality curl http://staging:8081/job/test-job/build
Note: Always backup production data before starting staging upgrade tests.
Warning: Do not run production jobs on staging during upgrade testing.

7. Migrating to New Server

Example: Backup and Restore Jenkins Configuration

tar -czf jenkins-backup-2026-01-01.tar.gz /var/lib/jenkins
Step Description Action
1. Backup Configuration Archive Jenkins home directory Run tar -czf jenkins-backup.tar.gz /var/lib/jenkins
2. Transfer Files Move backup to new server Use scp or sftp
3. Install Jenkins Set up Jenkins on new server Follow installation guide for OS
4. Restore Configuration Extract backup to Jenkins home Run tar -xzf jenkins-backup.tar.gz -C /var/lib/jenkins
5. Verify Plugins Ensure plugin versions match Check /var/lib/jenkins/plugins/
Note: Ensure Jenkins user has proper permissions on the new server.
Warning: Backups should be tested before migration to avoid data loss.

Migration Steps Summary

  • Prepare backup of Jenkins home directory
  • Transfer files securely to new server
  • Install Jenkins on target machine
  • Restore configuration and verify plugins
  • Test jobs and configurations post-migration

8. Using Configuration as Code for Migration

Example: Basic Jenkins Configuration as Code Setup

jenkins:
  systemMessage: "Welcome to Jenkins Configuration as Code"
  adminAddress: admin@example.com
  useSecurity: true
  authorizationStrategy:
    loggedInUsersCanDoAnything: false
  securityRealm:
    local:
      users:
        - id: "admin"
          password: "secret123"
Property Description Values Notes
jenkins.systemMessage System message displayed on Jenkins dashboard string Optional, shown to users on login
jenkins.adminAddress Admin contact email address string Used in notifications and logs
jenkins.useSecurity Enable or disable security features true / false Default: true
jenkins.authorizationStrategy Authorization strategy to use loggedInUsersCanDoAnything, roleBased Controls access control policies
jenkins.securityRealm Authentication method local, ldap Defines how users are authenticated
Note: Configuration as Code (JCasC) is a plugin that allows Jenkins to be configured via YAML files, which makes migration and version control easier.

Example: Migrating Jenkins Jobs with JCasC

jobs:
  - name: "example-job"
    project:
      scm:
        git:
          url: "https://github.com/example/repo.git"
          branch: "main"
      triggers:
        - pollSCM: "H/5 * * * *"
      builders:
        - shell: "echo 'Hello World'"

Migration Steps Using JCasC

  • Install the configuration-as-code plugin in Jenkins
  • Create a YAML file with your desired configuration
  • Use JENKINS_URL/configuration-as-code to apply the config
  • Validate that all jobs and settings are correctly migrated
Warning: Ensure that all plugins used in the old Jenkins instance are compatible with the new version before applying JCasC configurations.

9. Handling Breaking Changes

Note: Jenkins 2.401+ includes several breaking changes that require manual intervention during migration.
Change Description Action Required
Groovy Script Security Script security policy now blocks unsafe Groovy scripts by default. Review and update Groovy scripts to comply with new security rules or use ScriptApproval.
JDK 17 Requirement Jenkins now requires JDK 17 or higher to run. Update Jenkins server environment to use JDK 17+ before upgrading.
Plugin API Changes Some plugin APIs have been deprecated or changed in jenkins-core. Check plugin compatibility and update plugins to versions supporting new APIs.

Example: Updating Script Approval

// Before: Unrestricted script
def result = sh(script: 'echo "Hello World"', returnStdout: true)

// After: Approved script with ScriptApproval
import jenkins.model.Jenkins
import org.jenkinsci.plugins.scriptsecurity.scripts.ScriptApproval

def script = "sh(script: 'echo \"Hello World\"', returnStdout: true)"
ScriptApproval.get().approveScript(script)

Breaking Changes Summary

  • DEPRECATED Old Groovy sandbox policies are no longer effective.
  • NEW Jenkins now enforces strict JDK versioning.
  • EXPERIMENTAL Plugin API changes may require code refactoring.

Migration Workflow for Breaking Changes

  1. Backup Jenkins configuration and job data.
  2. Ensure JDK 17+ is installed on the Jenkins server.
  3. Review plugin list for compatibility with new Jenkins version.
  4. Update plugins using the Plugin Manager or CLI tools.
  5. Test critical jobs in a staging environment before full migration.

10. Rolling Back Failed Upgrades

Note: Rolling back a Jenkins upgrade requires careful planning and execution to avoid data loss or system instability.

When a Jenkins upgrade fails, it's crucial to have a rollback strategy in place. The following steps outline how to revert to a previous stable version of Jenkins.

Action Description Details
Backup Current State Ensure all configurations and data are backed up before attempting rollback. Use Jenkins' built-in backup feature or manual archive of JENKINS_HOME.
Identify Previous Version Determine the last stable Jenkins version before the failed upgrade. Check Jenkins release notes or logs for the last working version.
Stop Jenkins Service Gracefully stop the Jenkins service to prevent data corruption. Use systemctl stop jenkins or equivalent command for your OS.
Replace Jenkins WAR Revert to the previous Jenkins WAR file. Replace /var/lib/jenkins/war/ with the older version's WAR file.
Restore Configuration Revert configuration files and plugins to a known good state. Restore JENKINS_HOME from backup if needed.
Restart Jenkins Start the Jenkins service with the older version. Use systemctl start jenkins or equivalent command for your OS.

Example: Rolling Back Jenkins WAR File

# Stop Jenkins service
sudo systemctl stop jenkins

# Backup current WAR file (optional)
sudo cp /var/lib/jenkins/war/cache/.../jenkins.war /var/lib/jenkins/war/cache/backup.war

# Replace with older version
sudo cp /path/to/previous/jenkins-2.401.3.war /var/lib/jenkins/war/cache/.../jenkins.war

# Restart Jenkins
sudo systemctl start jenkins
Warning: Ensure that all plugins are compatible with the older Jenkins version before rolling back. Incompatible plugins may cause Jenkins to fail to start or behave unexpectedly.

Rollback Steps Summary

  • Backup current Jenkins configuration and data.
  • Identify the last stable Jenkins version.
  • Stop the Jenkins service gracefully.
  • Replace the WAR file with a known working version.
  • Restore configuration files if necessary.
  • Restart Jenkins and verify functionality.

Was this article helpful?

Related Cheat Sheets