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:

docker run -ti --rm -v maven-repo:/root/.m2 -v $(pwd)/out:/pct/out -e ARTIFACT_ID=ssh-slaves -e VERSION=ssh-slaves-1.24 jenkins/pct

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.

docker run -ti --rm -v maven-repo:/root/.m2 -v $(pwd)/out:/pct/out -v my/jenkins.war:/pct/jenkins.war:ro -e ARTIFACT_ID=ssh-slaves jenkins/pct

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

docker run -ti --rm -v maven-repo:/root/.m2 -v $(pwd)/out:/pct/out -v my/jenkins.war:/pct/jenkins.war:ro -v my/plugin:/pct/plugin-src:ro jenkins/pct

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

docker run --rm -v maven-repo:/root/.m2 -v $(pwd)/out:/pct/out -e CHECKOUT_SRC=https://github.com/oleg-nenashev/job-restrictions-plugin.git -e VERSION=JENKINS-26374 jenkins/pct

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

docker run -ti --rm -v maven-repo:/root/.m2 -v $(pwd)/out:/pct/out -v my/jenkins.war:/pct/jenkins.war:ro -e ARTIFACT_ID=ssh-slaves,credentials -e DO_NOT_OVERRIDE_PCT_CHECKOUT=true -e jenkins/pct

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:

java -jar target/plugins-compat-tester-cli.jar \
  --working-dir $(pwd)/tmp/work \
  --include-plugins ${PLUGIN_ARTIFACT_ID} \
  --war jenkins.war --local-checkout-dir ${PLUGIN_SRC} \
  --mvn ${PATH_TO_MAVEN}

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:…