Skip to content

CONTRIBUTING.adoc

Latest commit

 

History

History
216 lines (154 loc) · 5.72 KB

CONTRIBUTING.adoc

File metadata and controls

216 lines (154 loc) · 5.72 KB
Raw

Contributing

We’d love to accept your patches and contributions to this project.

Prerequisites

  • JDK 21 or later (Java 17 was dropped from Jenkins weekly in Jan 2026 and from the LTS line in April 2026)

  • Maven 3.9 or later

  • For integration tests: a GCP project with the Compute Engine API enabled and billing active

Code Style

The project uses Spotless for code formatting, enforced during the build.

To auto-fix formatting on every build (recommended), set this in your ~/.m2/settings.xml:

<settings>
  [...]
  <activeProfiles>
    [...]
    <activeProfile>may-spotless-apply</activeProfile>
  </activeProfiles>
</settings>

See jenkinsci/plugin-pom#1017 for details. Alternatively, run mvn spotless:apply manually.

Quick Start

git clone git@github.com:jenkinsci/google-compute-engine-plugin.git
cd google-compute-engine-plugin
mvn verify                # compile + unit tests + package (integration tests are off by default)
mvn hpi:run               # launch Jenkins locally with the plugin at http://localhost:8080/jenkins

Code Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Testing

Unit Tests

mvn test

Integration Tests

Integration tests provision actual GCE instances, run pipelines, and take snapshots. They are disabled by default and expected to be run on a contributor’s own machine with a real GCP project.

Integration test classes must be suffixed IT.java (e.g. ComputeEngineCloudRestartPreemptedIT.java) to be picked up by Failsafe.

Why disabled in CI:

  • Requires a GCP project with billing — not feasible in public CI.

  • Exposing GCP credentials in CI is a security risk.

Prepare VM Images

The agent images need Java pre-installed. Packer scripts create and upload the images to your GCP project.

Linux image:

cd testimages/linux
bash setup-gce-image.sh

The default image has java on PATH. To also create a non-standard-java image (java at /usr/bin/non-standard-java) for ComputeEngineCloudNonStandardJavaIT:

bash setup-gce-image.sh non-standard-java

Use --recreate to rebuild or --delete to remove images.

Windows image:

bash testimages/windows/setup-gce-image.sh

The default username is jenkins and the default password is Agent007!. To use a custom password, set the JENKINS_PASSWORD environment variable before running the script:

export JENKINS_PASSWORD=your-secure-password
bash testimages/windows/setup-gce-image.sh

This creates a Windows Server 2022 image with Java 25 (Java 21 also works) and OpenSSH pre-installed. The Packer image build runs from any platform (macOS, Linux) — it does not require a Windows machine. Use --recreate to rebuild or --delete to remove.

Set Environment Variables

export GOOGLE_PROJECT_ID=your-project-id
export GOOGLE_CREDENTIALS_FILE=/path/to/sa-key.json
export GOOGLE_REGION=us-central1
export GOOGLE_ZONE=us-central1-a
export GOOGLE_SA_NAME=jenkins-agent-sa

For Windows tests, also export:

export GOOGLE_BOOT_DISK_PROJECT_ID=your-project-id
export GOOGLE_BOOT_DISK_IMAGE_NAME=jenkins-gce-integration-test-windows-jre
export GOOGLE_JENKINS_PASSWORD=Agent007!  # default; must match the password used during image build

Create a Service Account

See the IAM Credentials setup in the user documentation.

Run Integration Tests

Integration tests are disabled by default (-DskipITs=true in pom.xml). Enable them explicitly with -DskipITs=false.

Run all integration tests:

mvn verify -DskipITs=false

Run a specific integration test class:

mvn verify -Dskip.surefire.tests=true -DskipITs=false -Dit.test=ComputeEngineCloudRestartPreemptedIT

Run a specific integration test method:

mvn verify -Dskip.surefire.tests=true -DskipITs=false -Dit.test=ComputeEngineCloudRestartPreemptedIT#testIfNodeWasPreempted

Run Windows integration tests:

mvn verify -DskipITs=false -Dit.windows=true

Debugging Tests

Attach a remote debugger on port 5005.

Unit test (Surefire):

mvn test -Dtest=YourTestClass -Dmaven.surefire.debug=true

Integration test (Failsafe):

mvn verify -Dskip.surefire.tests=true -DskipITs=false -Dit.test=YourTestClassIT -Dmaven.failsafe.debug=true

Then connect your remote debug configuration to localhost:5005.

License

See LICENSE