jenkins/pct
Plugin Compat Tester - no longer published as a docker image
100K+
Generates a compatibility matrix for plugins against Jenkins core.
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 defaultCHECKOUT_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 defaultJAVA_OPTS
- Java options to be passed to the PCT CLIDEBUG
- 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 installedVolumes:
/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:
/pct/plugin-src
volume to inform the PCT about themPCT offers the CLI interface which can be used to run PCT locally.
PCT
and execute mvn clean install
PLUGIN_SRC
directory.mvn clean install -DskipTests
to initialize artifactsPCT
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*
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.
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.
docker run --rm -v maven-repo:/root/.m2 -v $(pwd)/out:/pct/out -e ARTIFACT_ID=job-restrictions -e DEBUG=true -p 5005:5005 -i jenkins/pct
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.
set JAVA_HOME=...
make demo PLUGIN_NAME=artifact-manager-s3 WAR_PATH=test-wars/mywar.war MVN_EXECUTABLE="C:\ProgramData\chocolatey\bin\mvn.exe"
docker pull jenkins/pct