Categorizing plugins

Plugin labels are shown to users:

• as categories in Jenkins before 2.224 and on theplugins site

• as tags in Jenkins from 2.224 and also on the plugins site.

Seethis Jenkins resource file (look forUpdateCenter.PluginCategory) for the localization overrides applied to labels by Jenkins.Other labels are categorized into generalMisc (custom-label-here) categories (Jenkins before 2.224) or displayed as is.

Two ways can be used to define these labels:

Plugin URL Override

Plugins are generally expected to provide a<url> to their documentation in their POM.Historically, these URLs have been pages on the Jenkins wiki, but can point anywhere.

This requirement no longer exists, but it may still be useful to define a documentation URL for plugins that do not specify the correct URL.

The fileresources/wiki-overrides.properties defines these wiki page overrides.

Deprecations

Plugins are considereddeprecated by Jenkins when either the update site metadata does one or both of the following:

• Uses the labeldeprecated for the plugin.This can be done via GitHub repository topics, or theresources/label-definitions.properties described above.Jenkins will use the plugin URL as the reference URL for the deprecation notice.

• Lists an entry with the plugin ID as key in the top-leveldeprecations map inupdate-center.json.This can be done through entries in theresources/deprecations.properties file.The value from the properties file will be used as the URL for the deprecation notice in Jenkins.This entry and URL take precedence over adeprecated label, i.e. when both are set, the URL from the top-level element shall be used.

These two different approaches to plugin deprecation accomplish complementary goals:

• The label approach is very simple and can easily be done by plugin maintainers themselves via GitHub labels.It is also backward compatible with any earlier version of Jenkins — it will just show the deprecation as a regular label.Additionally, it doesn’t bloat the JSON file size at all, since no special URL is needed.

• The top-leveldeprecations element allows specifying a URL different from the plugin documentation URL as well as deprecating plugins no longer being distributed.Especially the latter is a common requirement when plugins integrate with services that no longer exist:It makes no sense to continue distributing them, but everyone having them already installed should be informed about it.

Removing plugins from distribution

The update center generator allows to specify that certain plugins, or plugin releases, should not be included in the output.

There are various reasons to need to do this, such as:

• A plugin release causes major regressions and a fix is not immediately available.

• A plugin integrates with a service that has been shut down.

Both use cases (entire plugins, or specific versions) are controlled via the fileresources/artifact-ignores.properties.See that file for usage examples.

Such plugins typically should get a corresponding deprecation entry inresources/deprecations.properties.

Security warnings

Since Jenkins 2.32.2 and 2.40, Jenkins can display security warnings about core and plugins.These warnings are part of the update center metadata downloaded by Jenkins.These warnings are defined in the fileresources/warnings.json.

Invocation

Build (mvn clean verify) the generator and then invoke it as follows:

The tool also supports batch mode execution, generating multiple update sites with a single invocation:

filename.txt is a text file with a list of arguments on each line.Lines that start with# are comments and ignored.Example:

For a full list of arguments, invoke the tool as follows:

Preparing local execution

Running./site/generate.sh will first create the batch mode control file./tmp/args.lst, before actually starting the tool.The following steps are therefore useful when trying to generate output corresponding to the real update sites during development:

1. Implement changes insrc/main/.

2. Run./site/generate.sh until the Java tool is actually launched, then abort. This requires some environment variables to be defined.

3. Edittmp/args.lst, changing or removing the--key,--certificate, and--root-certificate arguments as necessary.

4. Runjava -Dfile.encoding=UTF-8 -jar target/update-center2-*-SNAPSHOT-bin/update-center2-*-SNAPSHOT.jar --arguments-file tmp/args.lst

Alternatively, the closest you can get to real executions in local development:

1. Implement changes insrc/main/.

2. Deploy a snapshot usingmvn deploy. Requires an account in the Jenkins project, seeDeploying changes below.

3. Editsite/generate.sh to reference the specific snapshot you deployed (including timestamp) where it is downloaded usingwget, see previous build output.

4. Optionally, to speed things up, editsite/generate.sh and remove the arguments--downloads-directory "$DOWNLOAD_ROOT_DIR" from some of the invocations.

5. Run./site/generate.sh <www-dir> <downloads-dir>. The first argument is the output directory for metadata, the second argument is the output directory for downloads and unused unless the previous step 4 was skipped.

Running within an IDE

The project various artifacts to be used on a site hosting a jenkins update centerThe project produces a jar and a zip file containing all the required dependencies to run the generator.

If you want to run the generator from within your development environment,you can try to use the appassembler plugin as described below.The exec:java plugin won’t work.

Deploying changes

./site/generate.sh downloads and executes a specified version ofupdate-center2.This is different from earlier iterations of this tool that always rebuilt from source.The current iteration requires a (possible snapshot deployment) first, that is then referenced in./site.generate.sh.

Consequently, merging larger-scale changes to both the tool itself and the wrapper script need to be mindful of this dependency:A new release (or at minimum a snapshot deployment) is needed, which is then referenced in./site/generate.sh.

Working with htaccess/mod_rewrite rules

The wrapper scriptsite/generate.sh calls the scriptsite/generate-htaccess.sh with chosen arguments.The latter script will generate the.htaccess file mostly containing mod_rewrite rules to redirect requests to appropriate tiered update sites.To learn more about tiers, seeLAYOUT.md.

To test changes tosite/generate-htaccess.sh, runsite/test/test.sh.It executessite/generate-htaccess.sh and places it inside an Apache HTTPD Docker container and tests whether redirect rules are correctly applied.

Working with certificates

To sign JSON output files, create a development certificate:

Then add these arguments to your tool invocation (or arguments file):

To have your Jenkins instance accept update site JSON signed with this certificate, create a directoryupdate-center-rootCAs/ in the Jenkins home directory, and copy thedemo.crt file in there.Once update site JSON files are generated, configure Jenkins to download them inManage Jenkins » Manage Plugin » Advanced:Either set up a local HTTP server so the URL would be something likehttp://localhost:8000/update-center.json, or specify afile:// URL likefile:///Users/yourname/git/update-center2/www2/update-center.json

Filtering Java versions

The--java-version <version> CLI argument can be used to filter plugins based on their minimum Java version requirement.By default such filtering happens based on theMinimum-Java-Version manifest entry provided in Plugin HPIs starting fromMaven HPI Plugin 3.0 andPlugin POM 3.29.

Plugin HPIs withoutMinimum-Java-Version will be accepted by default.If you want to create an update center for old Java, use the--limit-plugin-core-dependency option to set the filter for core dependencies in plugins.