How to Test on Multiple Java Versions with GitHub Actions

A matrix on java-version drives setup-java so the same suite runs against every JDK you ship on.

Define a java-version matrix and pass each value to actions/setup-java, choosing a distribution like temurin. Maven or Gradle then runs the suite once per JDK.

Steps

• Add strategy.matrix.java-version with the JDKs you support (for example 17, 21).
• Pass ${{ matrix.java-version }} and a distribution to actions/setup-java.
• Run mvn -B verify (or ./gradlew test) to execute the suite.

Workflow

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        java-version: ['17', '21']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: ${{ matrix.java-version }}
          cache: maven
      - run: mvn -B verify

Gotchas

• Quote version numbers so YAML does not coerce 21 into something unexpected.
• Pick one distribution (temurin, zulu, corretto) and keep it consistent across the matrix.
• The cache: maven input keys on your lockfiles, so it only helps when those are committed.

Related guides