jenkins/pct pulls statistics

Plugin Compatibility Tester (PCT)

This is no longer published as a Docker image and is only kept for historical reasons

Generates a compatibility matrix for plugins against Jenkins core.

Running PCT

Running PCT in Docker

It is recommended to run PCT in the prepared Docker image. You can find it here.

Examples

This command will clone of a repository and run PCT against the latest Jenkins Core:

This command will run PCT for the latest plugin version against the specified Jenkins WAR. PCT supports running against SNAPSHOT builds, but PCT will have to install local Maven artifacts in such case.

This command will run PCT against custom versions of Jenkins and the plugin specified by volumes.

The command below will run PCT for a branch in a custom repository.

Full PCT runs using a war file as input with Docker

The PCT cli supports to pass a war file containing plugins (generated with Custom war Packager for example) as input, in this case the version of the plugins is infered from the war file contents.

In such scenarios is tipical to want to run the PCT for all plugins contained in the war file, to avoid having to spawn a new docker container for each plugin you can use the env variables DO_NOT_OVERRIDE_PCT_CHECKOUT=true to let the PCT CLI (instead of the run-pct script) checkout the proper versions of the plugins and make sure the PCT does not stop before testing all plugins.

By using those env variables you can pass a comma separated list of plugins ids using the ARTIFACT_ID env variable

Configuration

Environment variables:

• ARTIFACT_ID - ID of the artifact to be tested. The image will be able to determine this ID automatically if CHECKOUT_SRC or /pct/plugin-src are defined. • VERSION - tag/commit/branch to be checked out and tested. master by default • CHECKOUT_SRC - Custom Git clone source (e.g. https://github.com/oleg-nenashev/job-restrictions-plugin.git). https://github.com/jenkinsci/${ARTIFACT_ID}-plugin.git by default • JAVA_OPTS - Java options to be passed to the PCT CLI • DEBUG - Boolean flag, which enables the Remote Debug mode (port == 5000) • M2_SETTINGS_FILE - If set indicates the path of the custom maven settings file to use (see volumes below) • INSTALL_BUNDLED_SNAPSHOTS - Install JAR and plugin snapshots to local repository. true by default. • SKIP_LOCAL_SNAPSHOT_INSTALLATION - If exists WAR snapshots (core and plugins) will not be installed, if not present war snapshots will be installed

Volumes:

• /pct/plugin-src - Plugin sources to be used for the PCT run. Sources will be checked out if not specified • /pct/jenkins.war - Jenkins WAR file to be used for the PCT run • /pct/m2-settings.xml - Custom Maven Settings (optional) if M2_SETTINGS_FILE environment variable exists run-pct will ignore this location and use the one specified in the variable • /pct/out - Output directory for PCT. All reports will be stored there • /pct/tmp - Temporary directory. Can be exposed to analyze run failures • /root/.m2 - Maven repository. It can be used to pass settings.xml or to cache artifacts

:exclamation: Note that the entrypoint script of the PCT docker image tries to checkout the plugin sources before invoking the PCT if no war is provided. That means for plugins relying on PreCheckoutHooks (like multimodule ones) the standard docker run will fail to get sources as the PreCheckoutHooks are not run by the docker image entrypoint script. In that case possible workarounds are:

• Using a war file • Download the sources of the plugin and use the /pct/plugin-src volume to inform the PCT about them • Use the docker image but override the entry point and run manually the PCT inside the image • Run the PCT manually as explained below

Running PCT manually

PCT offers the CLI interface which can be used to run PCT locally.

• Download PCT and execute mvn clean install • Download plugin sources to a PLUGIN_SRC directory. • Checkout the plugin repo to a tag/commit/branch you want to test • Run mvn clean install -DskipTests to initialize artifacts • Go to PCT folder and run the CLI (make sure to modify paths according to your system). Example:

You can run the CLI with the -help argument to get a full list of supported options.

:exclamation: For the moment testing more than one plugin at once requires plugins to be released, so for testing SNAPSHOTS you need to execute the last step for every plugin you want to test*

Running PCT with custom Java versions

You can run the example by running the following command:

make demo TEST_JDK_HOME=${YOUR_JDK_HOME} PLUGIN_NAME=git When using the Docker image, it is possible to use JDK_VERSION variable to select the version to use. The version needs to be bundled in the docker image. Currently Java 17 and Java 11 are bundled (JDK_VERSION= {17, 11}). make demo-docker JDK_VERSION=17 PLUGIN_NAME=git

Full list of options be found here.

Developer Info

Debugging PCT in Docker

If you need to debug a dockerized PCT instance, use the -e DEBUG=true -p 5005:5005 flags and then attach to the container using Remote Debugger in your IDE.

Running PCT Makefiles on Windows

Plugin Compat Tester support Windows on its own, but it might be tricky to get the development makefiles running there. The default guidance it to use Docker, but it might be impossible in some cases.

One needs to install Make and Maven on Windows (e.g. using Chocolatey packages) and then to properly setup the environment.

Useful links

• Devoxx '11 BOF Presentation about Plugin Compat Tester is available here. This presentation is partially obsolete (GAE feature was removed in recent versions)