How to Upgrade Jenkins: Core Architecture and Methods Explained

Jenkins upgrades are handled automatically by the UpdateCenter class which polls remote update sites, compares versions via UpgradeService, and provides a UI through UpgradeSiteAction, allowing administrators to download new core versions and restart safely.

Upgrading Jenkins is a critical maintenance task that ensures your automation server receives security patches and new features. In the jenkinsci/jenkins repository, the upgrade mechanism is built directly into the core Java classes, eliminating the need for external scripts or manual war file replacement in most scenarios. This guide examines the source code architecture behind how to upgrade Jenkins safely using the built-in update center infrastructure.

Jenkins Upgrade Architecture

The Jenkins upgrade system is a self-contained framework within the core codebase that detects, downloads, and applies new versions automatically. At its foundation, the architecture relies on the UpdateCenter singleton to coordinate version checks across configured remote sites.

UpdateCenter

The UpdateCenter class serves as the central coordinator for all update operations. Located in [core/src/main/java/hudson/model/UpdateCenter.java](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/hudson/model/UpdateCenter.java), it maintains a list of UpdateSite instances and stores the latest available core version as a VersionNumber object. The class exposes the getCoreVersion() method to retrieve the newest available version and updateAllSites() to force an immediate refresh of metadata from remote sources.

UpgradeService and Administrative Monitoring

When a newer version is detected, the UpgradeService ([core/src/main/java/jenkins/upgrade/UpgradeService.java](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/jenkins/upgrade/UpgradeService.java)) implements both RootAction and AdministrativeMonitor to expose upgrade status to administrators. This extension registers a warning banner on the Jenkins dashboard when the running version is older than the latest available core version.

UpgradeSiteAction UI Endpoint

The web interface for upgrades is provided by UpgradeSiteAction ([core/src/main/java/jenkins/upgrade/UpgradeSiteAction.java](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/jenkins/upgrade/UpgradeSiteAction.java)), which maps to the /upgradeInfo URL. This RootAction renders the upgrade details page where administrators can view release notes and trigger download operations.

UpdateSite Remote Metadata

Each remote update source is represented by the UpdateSite class ([core/src/main/java/hudson/model/UpdateSite.java](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/hudson/model/UpdateSite.java)). This class handles the HTTP retrieval of update-center.json from endpoints like https://updates.jenkins.io, parsing the core version block and download URLs.

Jenkins Singleton Initialization

The Jenkins class ([core/src/main/java/jenkins/model/Jenkins.java](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/jenkins/model/Jenkins.java)) hosts the global UpdateCenter instance and schedules the periodic background task that triggers update checks automatically on startup.

The Jenkins Upgrade Process Step by Step

Understanding the execution flow helps administrators troubleshoot blocked upgrades or network issues.

1. Initial Check Scheduling — Upon startup, Jenkins invokes an @Initializer that schedules periodic calls to UpdateCenter.updateAllSites().
2. Metadata Retrieval — Each configured UpdateSite downloads the update-center.json file containing the latest core version string and download URL.
3. Version Comparison — UpdateCenter parses the retrieved version using VersionNumber and compares it against Jenkins.getVersion().
4. Alert Generation — If newer, UpgradeService activates its AdministrativeMonitor, displaying the upgrade banner in the UI.
5. Admin Interaction — Navigating to /upgradeInfo triggers UpgradeSiteAction to render upgrade details and available actions.
6. Download and Restart — Confirming the upgrade initiates a background download of the new jenkins.war, which replaces the current instance during the next safe restart via Jenkins.doSafeRestart().

Programmatically Managing Upgrades

Administrators can interact with the upgrade system programmatically using Groovy scripts via the Script Console.

Force an immediate update center refresh:

// Force Jenkins to refresh update site metadata immediately
Jenkins.instance.getUpdateCenter().updateAllSites()

Check for available upgrades:

import hudson.util.VersionNumber
def current = Jenkins.instance.getVersion()
def latest  = Jenkins.instance.getUpdateCenter().getCoreVersion()
if (latest != null && latest > new VersionNumber(current.toString())) {
    println "Upgrade available: ${latest} (current: ${current})"
} else {
    println "Jenkins is up‑to‑date."
}

Access upgrade status programmatically:

import jenkins.upgrade.UpgradeService
def monitor = UpgradeService.get()
if (monitor != null && monitor.isActive()) {
    println "🔔 ${monitor.getMessage()}"
}

Summary

• Jenkins upgrades are managed internally through the UpdateCenter, UpdateSite, UpgradeService, and UpgradeSiteAction classes according to the jenkinsci/jenkins source code.
• The system polls https://updates.jenkins.io periodically to detect new core versions automatically.
• UpgradeService implements AdministrativeMonitor to display dashboard banners when updates are available.
• The /upgradeInfo endpoint provided by UpgradeSiteAction serves the administrative interface for downloading and applying updates.
• Programmatic control is available via Groovy scripts calling UpdateCenter methods directly.

Frequently Asked Questions

Can I upgrade Jenkins without downtime?

Jenkins requires a restart to load a new core version because the executable resides in the running war file. However, you can use the safe restart feature to wait for running builds to complete before restarting, minimizing disruption.

Where does Jenkins store update metadata?

Metadata is cached in memory within the UpdateCenter instance and stored persistently in the UpdateSite configuration files within the Jenkins home directory. The raw JSON from updates.jenkins.io is parsed on each refresh cycle.

How do I disable automatic update checks?

You can disable automatic checks by removing the update site URLs from the Jenkins Update Center configuration in the Plugin Manager, or by setting the appropriate system properties to block outgoing connections to the update server.

What happens if an upgrade download fails?

If the download fails, the UpdateCenter marks the job as failed and logs the error. The existing Jenkins instance continues running unaffected. Administrators can retry the download from the /upgradeInfo page or via the Script Console by invoking the update methods again.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}