# How to Upgrade Jenkins: Core Architecture and Methods Explained

> Learn how to upgrade Jenkins easily. This guide explains core architecture and methods for seamless Jenkins upgrades, ensuring your CI/CD pipeline stays current and secure.

- Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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/main/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/main/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/main/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/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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:

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

```

Check for available upgrades:

```groovy
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:

```groovy
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.