# Understanding UpdateSite for Jenkins Plugin Updates and Plugin Management

> Discover how Jenkins UpdateSite manages trusted plugin updates and security, ensuring reliable plugin discovery and signature verification for your controller.

- Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins)
- Tags: internals
- Published: 2026-07-28

---

**The `UpdateSite` class acts as the trusted gateway between your Jenkins controller and remote plugin repositories, managing metadata retrieval, signature verification, and the discovery of available plugins and security updates.**

In the `jenkinsci/jenkins` repository, the **UpdateSite** serves as the cornerstone of the plugin lifecycle, supplying the metadata required to discover, download, and validate plugins. This article explores how the `hudson.model.UpdateSite` class drives Jenkins plugin updates and plugin management by interfacing with remote update centers, caching data locally, and ensuring cryptographic integrity.

## What Is an UpdateSite?

An `UpdateSite` represents a remote location hosting an [`update-center.json`](https://github.com/jenkinsci/jenkins/blob/main/update-center.json) file. This JSON payload contains authoritative metadata about the Jenkins core version, available plugins, dependencies, compatibility constraints, health scores, deprecations, and security warnings. The primary implementation resides in [`hudson/model/UpdateSite.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/UpdateSite.java), where the class encapsulates logic for fetching, validating, and exposing this metadata to the Jenkins update subsystem.

## Caching, Refresh Scheduling, and Connectivity

Jenkins maintains a local copy of the update metadata under `$JENKINS_HOME/updates/<site-id>.json` to minimize network traffic. The `UpdateSite` object tracks temporal state through fields like `dataTimestamp`, `lastAttempt`, and `retryWindow` to determine when a refresh is necessary.

The `isDue()` method evaluates these timestamps to decide whether to re-fetch data from the remote source, preventing excessive server load. Before attempting downloads, Jenkins may verify external network access using the `connectionCheckUrl` field, which defaults to `http://www.google.com/`.

## Plugin Discovery and Update Detection

### Finding Available Plugins

The `getAvailables()` method in [`hudson/model/UpdateSite.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/UpdateSite.java) constructs a list of plugins that are available for installation but not yet present on the controller. It filters the `Data.plugins` collection for entries where `Plugin.getInstalled()` returns `null`, returning a list of `UpdateSite.Plugin` objects representing candidates for installation.

### Detecting Installed Plugin Updates

To identify upgrades, `getUpdates()` iterates over currently installed plugins (represented as `PluginWrapper` instances) and invokes `getUpdateInfo()` on each. This returns a collection of plugins where the update site hosts a newer version than the one currently deployed, enabling the Jenkins UI to notify administrators of available updates.

### Compatibility and Dependency Validation

Each plugin entry includes metadata about required core versions, explicit dependencies, optional dependencies, and compatibility flags. The `isCompatible()` and `isCompatibleWithInstalledVersion()` methods evaluate whether a plugin can be safely installed or upgraded given the current Jenkins environment, preventing system instability from incompatible installations.

## Security Validation and Warning Distribution

### Signature Verification

Security is enforced through cryptographic validation. The `updateData(...)` method passes retrieved JSON through `JSONSignatureValidator` to verify digital signatures before persisting the data to disk. This ensures that metadata has not been tampered with during transit, establishing the update site as a trusted authority.

### Security Warnings Integration

Update sites embed security advisory data through `Warning` objects. The `UpdateSiteWarningsMonitor` (referenced in [`hudson/model/UpdateSiteWarningsMonitor.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/UpdateSiteWarningsMonitor.java)) surfaces these warnings to administrators, alerting them to known vulnerabilities in specific plugin versions or the Jenkins core itself.

## Integration with UpdateCenter

While `UpdateSite` handles individual remote sources, [`hudson/model/UpdateCenter.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/UpdateCenter.java) aggregates multiple `UpdateSite` instances. This architecture allows Jenkins to pull plugins from several sources simultaneously, such as the community update center and corporate mirrors. The `UpdateCenter` delegates to each site for data retrieval, plugin lookup, and the creation of installation jobs, orchestrating the overall plugin management workflow.

## Working with UpdateSite Programmatically

The Jenkins API exposes `UpdateSite` functionality for administrative scripts and plugins.

### Listing Available Plugins

Retrieve the default update site and enumerate installable plugins:

```java
UpdateCenter uc = Jenkins.get().getUpdateCenter();
UpdateSite defaultSite = uc.getSite(UpdateCenter.DEFAULT_ID);
List<UpdateSite.Plugin> available = defaultSite.getAvailables();
available.forEach(p -> System.out.println(p.getDisplayName() + " – " + p.version));

```

### Checking for Updates and Refreshing Data

Trigger a background check for available updates:

```java
UpdateCenter uc = Jenkins.get().getUpdateCenter();
UpdateSite site = uc.getSite(UpdateCenter.DEFAULT_ID);
if (!site.getUpdates().isEmpty()) {
    // Asynchronously fetch the latest update‑center JSON
    site.updateDirectly();   // returns a Future<FormValidation>
}

```

### Verifying Signatures Manually

Validate the integrity of update site data programmatically:

```java
UpdateSite site = Jenkins.get().getUpdateCenter().getSite("my-mirror");
FormValidation validation = site.doVerifySignature(); // throws IOException
System.out.println(validation.kind); // OK or ERROR

```

## Summary

- **UpdateSite** acts as the bridge between Jenkins and remote plugin repositories, defined in [`hudson/model/UpdateSite.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/UpdateSite.java).
- It caches [`update-center.json`](https://github.com/jenkinsci/jenkins/blob/main/update-center.json) locally under `$JENKINS_HOME/updates/` and uses timestamp tracking via `isDue()` to manage refresh cycles.
- **Plugin discovery** uses `getAvailables()` to find new plugins, while `getUpdates()` identifies upgrades for existing installations.
- **Security** is enforced through `JSONSignatureValidator` signature checks in `updateData()` and vulnerability warnings via `UpdateSiteWarningsMonitor`.
- **Compatibility** is validated through `isCompatible()` methods that check dependencies and core version requirements.
- The **UpdateCenter** ([`hudson/model/UpdateCenter.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/UpdateCenter.java)) coordinates multiple `UpdateSite` instances to support distributed plugin sources.

## Frequently Asked Questions

### What file format does Jenkins use for update site metadata?

Jenkins expects a JSON file named [`update-center.json`](https://github.com/jenkinsci/jenkins/blob/main/update-center.json) hosted at the remote update site URL. This file contains structured metadata about available plugins, their versions, dependencies, security warnings, and compatible Jenkins core versions.

### How does Jenkins verify the integrity of plugin metadata?

The `UpdateSite.updateData()` method validates downloaded JSON using `JSONSignatureValidator` to check cryptographic signatures before persisting the data. This signature verification ensures the metadata originates from a trusted source and has not been modified in transit.

### Where does Jenkins store cached update site data locally?

Jenkins persists downloaded update metadata to `$JENKINS_HOME/updates/<site-id>.json`, where `<site-id>` corresponds to the identifier of the configured update site (such as `default`). This local cache enables offline browsing of available plugins and reduces network load.

### Can Jenkins administrators configure multiple update sites simultaneously?

Yes. The `UpdateCenter` class aggregates multiple `UpdateSite` instances, allowing administrators to configure primary and secondary update sources through the Jenkins UI. This supports scenarios where plugins must be retrieved from both the public Jenkins update center and internal corporate mirrors.