Testing a Maven project using a Toolchain and GitHub Actions

If you want to integration-test your Maven project, you might already use GitHub Actions.

Testing with a Maven toolchain is a little more complex to set up. This tutorial will show how I did this for the maven-jlink-plugin.

Creating your workflow

Create a new workflow, if you haven’t already. The workflow Java with Maven is a good starting point.

# This workflow will build a Java project with Maven
# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-maven

name: Java CI with Maven

on: [ push, pull_request ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up JDK 11
      uses: actions/setup-java@v1
      with:
        java-version: 11
    - name: Build with Maven
      run: mvn -B package --file pom.xml

Set up your matrix

Modify as wanted, e.g. Ubuntu, Windows with Java 11 and 15.

jobs:
  build:

    strategy:
      matrix:
        os: [ ubuntu-latest, windows-latest ]
        java: [ 11, 15 ]
      fail-fast: false

    runs-on: ${{ matrix.os }}

Install the Toolchain JDK first

Now, the important part is to install a JDK which you want to use as a Toolchain JDK. I use jabba for this, but other means will also work. Just make sure you get a nice environment variable from it.

I install it with the jdk-via-jabba-action and save the location to the env-variable $TOOLCHAIN_JDK. Make sure to place this before the setup-java-action:

jobs:
  build:
      # …
      - name: Install Toolchain JDK
        if: ${{ matrix.java == '8' }}
        uses: battila7/jdk-via-jabba@v1
        with:
          jdk: adopt-openj9@1.11.0-7
          javaHomeEnvironmentVariable: TOOLCHAIN_JDK

Create your toolchain.xml file

Now, maven must be told that there is another JDK available for the toolchain plugin. We need to create a file $HOME/.m2/toolchains.xml. As the write-file-action did not work for me, I reverted back to a simple bash HEREDOC to write a file using GitHub Actions. Place the following snipped directly after the jabba-action, but before the setup-java action:

jobs:
  build:
      # … other actions
      - name: Set up Toolchain
        if: ${{ matrix.java == '8' }}
        shell: bash
        run: |
          mkdir -p $HOME/.m2 \
          && cat << EOF > $HOME/.m2/toolchains.xml
          <?xml version="1.0" encoding="UTF8"?>
          <toolchains>
            <toolchain>
              <type>jdk</type>
                <provides>
                  <version>11</version>
                  <vendor>adopt</vendor>
                </provides>
                <configuration>
                  <jdkHome>${{ env.TOOLCHAIN_JDK }}</jdkHome>
                </configuration>
            </toolchain>
          </toolchains>
          EOF

As you can see I also added an if clause: It will only be used if the matrix runs with java 8, so I can check if the integration tests requiring java9+ will work by using a toolchain.

Maven will now use adopt-openj9@1.11.0-7 as a JDK11 toolchain java if needed.

Putting it all together

This is my complete GitHub Action with Toolchains for the maven-jlink-plugin: