Jenkins : Upgrade wizard

JENKINS-33568 tracks this


Users upgrading to 2.0 should get the same level of functionalities to users who are installing 2.0 from scratch.

Staged Fixes

In the interest of solving this in time for 2.0, the fix will be staged:

Step 0: stop-gap fix (JENKINS-33662)

You upgrade your binary from 1.x to 2.x (imagine apt-get install jenkins=2.0), you reboot Jenkins (imagine service jenkins restart), then your Jenkins comes up in operational status like your past 1.x→1.y upgrade. It will start executing builds and otherwise function normally.

When a user with administrative right access Jenkins web UI, s/he gets a highly visible notice that cannot be ignored on every page of Jenkins to steer him/her into going through the wizard. The following image is an example of this for illustration only:

(The wording will be changed to "Install the rest of 2.0 functionalities" or something like that.)

In more practical terms, this means the followings:

  • if the instance is unsecured (the default state of 1.x installation), then every anonymous user visiting the page will see this banner
  • if the instance is secured, only subset of users will see this after logging in.

Clicking this link will hit the endpoint that schedules the installation of Pipeline as Code plugins and take the user to the update center UI.

As the admin user is going through the setup wizard, Jenkins will continue to function as usual for non-admin users.

Step 1: recommended plugin installation (JENKINS-33663)

Instead of taking users straight to the update center UI, we'll take users through a modified version of the setup wizard. Some wording changes might be needed (TODO: try the setup wizard to see if the flow is adequate from the perspective of upgrading users.)

The user gets a choice of installing the recommended set of plugins (ongoing discussion on whether or not that set should be different from what we already have), or skip the plugin addition altogether.

Step 2: secure by default

Build on step 1, and add the security part of the setup wizard.

If Jenkins is already secured, this part shall be skipped.


Step 0 is expected to land before beta. Step 1 development shall begin ASAP, but it's targeted to 2.1, which is the release that happens one week after 2.0. Step 2 development should begin after step 1 is completed.


  • Due to the release time line, the amount of effort we can spend on this is limited. I think this proposal minimizes the amount of changes that need to happen to get this in.
  • This design ensures that Jenkins comes up functional. Jenkins admin can come in later and go through the upgrade wizard when s/he is ready.
  • The default path for upgrading users should be to get the recommended set of functionalities. This design does that by reusing the existing setup wizard.
  • There should be an option for people who know what they are doing to stay minimal and opt out of 2.0 functionalities. This design does that by reusing the existing setup wizard.

Implementation Notes

PageDecorator provides a means to put up this kind of banner.


upgrade-wizard.png (image/png)