Ensure valid plugin version used when `--latest=false`

[rrjjvv]

What feature do you want to see added?

As of this moment there is bad/incorrect data (details below) in the update center causing the installation of a specific plugin to fail. It claims a dependency on a plugin version that does not exist, but there is a version that satisfies the bounds. It would be nice if the tool was able to handle this case. Alternatively, outputting a message warning that the resolved version isn't valid would be helpful.

I have not looked at the code yet, but I'm assuming this isn't a bug in the tool (and that it wasn't intended to treat versions like full range specifications).

UC data for problematic plugin

The plugin I'm installing is git-forensics:3.2138.vf25ea_d549e33 (latest released version):

$ jq '.plugins."git-forensics"."3.2138.vf25ea_d549e33"' plugin-versions.json
{
  "buildDate": "Sep 25, 2025",
  "dependencies": [
    {
      "name": "commons-lang3-api",
      "optional": false,
      "version": "3.18.0-98.v3a_674c06072d"
    },
    {
      "name": "commons-text-api",
      "optional": false,
      "version": "1.14.0-194.v804a_dc3a_1b_d8"
    },
    {
      "name": "font-awesome-api",
      "optional": false,
      "version": "7.0.1-859.v128d3a_efb_6e5"
    },
    {
      "name": "forensics-api",
      "optional": false,
      "version": "3.1754.v2a_6613b_77002"
    },
    {
      "name": "plugin-util-api",
      "optional": false,
      "version": "6.1183.vdfd884091c0e"
    },
    {
      "name": "branch-api",
      "optional": false,
      "version": "2.1244.vf95c81f1641c"
    },
    {
      "name": "git",
      "optional": false,
      "version": "5.7.0"
    }
  ],
  "name": "git-forensics",
  "releaseTimestamp": "2025-09-25T19:18:00.00Z",
  "requiredCore": "2.516.3",
  "sha1": "Io9YiAtFBN3i3GvmhPASGs8BNtQ=",
  "sha256": "M6q+NYlVfQMZfYvd1fiQAnHn9pqlrtfegUn2S3zRN/M=",
  "url": "https://updates.jenkins.io/download/plugins/git-forensics/3.2138.vf25ea_d549e33/git-forensics.hpi",
  "version": "3.2138.vf25ea_d549e33"
}

Note it's calling for plugin-util-api:6.1183.vdfd884091c0e, which does not exist:

$ jq '.plugins."plugin-util-api"|keys' plugin-versions.json
[
<snip>
  "6.0.0",
  "6.1.0",
  "6.1154.ved7e7d3035a_5",
  "6.1157.vc75ef7129d86",
  "6.1165.v322e76215b_a_4",
  "6.1167.v022176c7e0ca_",
  "6.1192.v30fe6e2837ff"
]

Thus, jenkins-plugin-cli -p git-forensics:3.2138.vf25ea_d549e33 --latest=false fails because the transitive plugin doesn't exist at that version, but jenkins-plugin-cli -p git-forensics:3.2138.vf25ea_d549e33 --latest=true does work, since there is a valid/newer version. My desired/expected behavior would be that plugin-util-api:6.1192.v30fe6e2837ff is installed since it is the next valid version. (The fact that it happens to be the latest version as well is coincidence.)

Upstream changes

No response

Are you interested in contributing this feature?

Possibly, if it was straightforward.

[Zhenye-Na]

We are sharing some similar experience where we use the same argument. #797

Even on top of that

--jenkins-version: (optional) Version of Jenkins to be used. If not specified, the plugin manager will try to extract it from the WAR file or other sources. The argument can be also set using the JENKINS_VERSION environment variable.

We experienced that even passing in the jenkins-version, one of the plugins we used are still installed the latest version where it requires a newer jenkins version. Wondering if this could be grouped together, or I am more than happy to create a new issue

[MarkEWaite]

Thanks for the report.

I've also seen a failure in plugin BOM that might be related to that incorrectly declared dependency. I'm still exploring in order to better understand that failure. In the meantime, I've submitted a git forensics plugin bug report noting that it has declared a dependency on a plugin version that does not exist.

[rrjjvv]

Cool. So is the current thinking that this should have never happened in the first place? That it should have been caught at publication time, or detected/mitigated shortly thereafter via automation (e.g., automated BOM updates)?

Strange that it failed on the 'missed' update to 2.543, but not on the automated update for 2.542, but maybe that's part of what you're exploring.

[MarkEWaite]

Cool. So is the current thinking that this should have never happened in the first place?

Yes. The Apache release plugin Maven has safeguards that prevent a release that includes unreleased dependencies when those dependencies are snapshots. Jenkins plugin developers needs to evaluate unreleased dependencies with consistent version numbers. We have incrementals that allow a plugin developer to temporarily depend on a dependency that is precisely versioned but unreleased. They are not detected by the Apache Maven release plugin or by the process that generates Jenkins plugin releases on GitHub.

That it should have been caught at publication time, or detected/mitigated shortly thereafter via automation (e.g., automated BOM updates)?

I would have liked it to be caught at publication time, but I'm not sure of the techniques that are available to check for it. The Maven release plugin checks for snapshot dependencies. I'll need to discuss it with other Jenkins developers after the holidays. I'm not well versed in the details of Maven dependency management and how those dependencies are checked.

Strange that it failed on the 'missed' update to 2.543, but not on the automated update for 2.542, but maybe that's part of what you're exploring.

The Jenkins plugin bill of materials makes some compromises when running plugin tests together. I assume one or more of those compromises caused the issue to remain hidden until the recent updates. There have also been significant changes in the Jenkins test harness (upgrading from JUnit 4 to JUnit Jupiter). Those changes may have exposed the issue as well.

[rrjjvv]

We have incrementals that allow a plugin developer to temporarily depend on a dependency that is precisely versioned but unreleased. They are not detected by the Apache Maven release plugin or by the process that generates Jenkins plugin releases on GitHub.

I've never had to learn about that mechanism as none of my plugins have been published (only used in-house), but it makes sense how this might occur with that workflow. According to this that version was produced, but doesn't show up in the incremental repository... the oldest one is a few days/versions newer. Looking at other random plugins, they were showing their oldest version being around that date as well (Sep. 25-26). Not sure if that's a clue or not. At first I thought it was simply a three month retention policy in play (which could then explain the 2.542/2.543 discrepancy) but then came across one that had older versions.

The Jenkins plugin bill of materials makes some compromises when running plugin tests together. I assume one or more of those compromises caused the issue to remain hidden until the recent updates. There have also been significant changes in the Jenkins test harness (upgrading from JUnit 4 to JUnit Jupiter). Those changes may have exposed the issue as well.

Makes sense. I'd be curious whether that build truly pushed the artifact, or if it could have been deleted... that could explain things.

But back on topic and leaving the detective work to the professionals: this enhancement request was in response to a scenario that shouldn't have happened. Showing a warning (my second choice) seems like it would still be easy if the impossible were to happen again, but changing the behavior (my first choice) is probably not worth the risk/effort. Let me if you'd like me to close this (or feel free to do so yourself).

Re: #865 (comment), I think it is somewhat relevant based on the current issue title. In my case, "valid plugin" meant "version that is published and available for download" (something that could not be resolved by changing other plugin dependencies), whereas I think @Zhenye-Na defines "valid plugin" as "version usable/compatible" (but presumably they actually exist). Though we both want the same end result (a functional set of plugins not forced to their latest versions), it's a different problem IMO.

[MarkEWaite]

At first I thought it was simply a three month retention policy in play (which could then explain the 2.542/2.543 discrepancy) but then came across one that had older versions.

We have a 3 month retention policy for incrementals. We were originally retaining them indefinitely, but that was using too much storage in our artifact repository.

[rrjjvv]

We have a 3 month retention policy for incrementals. We were originally retaining them indefinitely, but that was using too much storage in our artifact repository.

Ah! That could explain a lot (making guesses on how things may be set up in your CI). One of the counter-examples I had seen was this plugin, which goes back a few years. Regardless of the reason, it's nice to know the intent.

[MarkEWaite]

One of the counter-examples I had seen was this plugin, which goes back a few years.

If you look inside the directories of that plugin, you'll see that the jar and pom files are no longer there. There appears to be a "module" file as the only remaining item.