GitHub Action for GraalVM

Set up your GitHub Actions workflow with a specific GraalVM distribution, and use it both as your JDK and for ahead-of-time Native Image compilation.

Key Features

This action:

• supports Oracle GraalVM releases, EA builds, GraalVM Community Edition (CE) releases, dev builds, GraalVM Enterprise Edition (EE) releases (set gds-token) 22.1.0 and later, Mandrel, and Liberica Native Image Kit (see Options)
• exports a $GRAALVM_HOME environment variable
• adds $GRAALVM_HOME/bin to the $PATH environment variable
  (native-image, javac, and other JDK tools can be invoked directly)
• sets $JAVA_HOME to $GRAALVM_HOME by default
  (can be disabled via set-java-home: 'false', see Options)
• supports x64 and aarch64/arm64
• supports dependency caching for Apache Maven, Gradle, and sbt (see cache option)

Templates

Quickstart Template

name: GraalVM build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: graalvm/setup-graalvm@v1
        with:
          version: '25.4'         # or '25.0' for LTS; See 'Options' for more details
          distribution: 'graalvm' # See 'Supported distributions' for available options
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Example step
        run: |
          echo "GRAALVM_HOME: $GRAALVM_HOME"
          echo "JAVA_HOME: $JAVA_HOME"
          java --version
          native-image --version
      - name: Example step using Maven plugin  # https://graalvm.github.io/native-build-tools/latest/maven-plugin.html
        run: mvn -Pnative package
      - name: Example step using Gradle plugin # https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html
        run: gradlew nativeCompile

Building a HelloWorld with GraalVM Native Image on Different Platforms

name: GraalVM Native Image builds
on: [push, pull_request]
jobs:
  build:
    name: HelloWorld on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
    steps:
      - uses: actions/checkout@v6

      - uses: graalvm/setup-graalvm@v1
        with:
          version: '25.0'
          distribution: 'graalvm'
          github-token: ${{ secrets.GITHUB_TOKEN }}
          native-image-job-reports: 'true'

      - name: Build and run HelloWorld.java
        run: |
          echo 'public class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } }' > HelloWorld.java
          javac HelloWorld.java
          native-image HelloWorld
          ./helloworld
      
      - name: Upload binary
        uses: actions/upload-artifact@v4
        with:
          name: helloworld-${{ matrix.os }}
          path: helloworld*

Template for GraalVM innovation releases

name: Oracle GraalVM Innovation Release build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: graalvm/setup-graalvm@v1
        with:
          version: '25.4' # or '25i-latest' for the latest innovation release
          distribution: 'graalvm'
          github-token: ${{ secrets.GITHUB_TOKEN }}

Template for Oracle GraalVM Early Access (EA) builds

name: Oracle GraalVM Early Access build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: graalvm/setup-graalvm@v1
        with:
          java-version: '25i5-ea' # or 'latest-ea' for the latest release
          distribution: 'graalvm'
          github-token: ${{ secrets.GITHUB_TOKEN }}

Template for Oracle GraalVM via GraalVM Download Service

Prerequisites

1. Obtain a token for the GraalVM Download Service. For this, replace your@email.com with your email address and run the following curl command:

   curl -sS -X POST "https://gds.oracle.com/api/20220101/licenseAcceptance" \
     -H "Content-Type: application/json" \
     -d "{ \"email\": \"your@email.com\", \"licenseId\": \"D53FA58D12817B3CE0530F15000A74CA\", \"type\": \"GENERATE_TOKEN_AND_ACCEPT_LICENSE\"}"

   The response should look like this:

   {"token":"<your-token>","status":"UNVERIFIED"}

2. Store the value of <your-token> as a GitHub Action secret. For the following template, we use the name GDS_TOKEN.

3. Check your emails and accept the license to activate the token.

4. Use java-version: '17' (or a specific version such as 17.0.13) and provide the GDS_TOKEN as shown in the following template:

   name: Build with Oracle GraalVM for JDK 17 via GDS
   on: [push, pull_request]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v6
         - uses: graalvm/setup-graalvm@v1
           with:
             distribution: 'graalvm'
             java-version: '17'
             gds-token: ${{ secrets.GDS_TOKEN }}
             github-token: ${{ secrets.GITHUB_TOKEN }}
         - name: Example step
           run: |
             java --version
             native-image --version

Template for GraalVM Enterprise Edition

Prerequisites

1. Download the version of GraalVM Enterprise Edition (EE) you want to run on GitHub Actions.

2. Use the GraalVM Updater to install the GraalVM components you need on GitHub Actions and accept the corresponding licenses.

3. Run $GRAALVM_HOME/bin/gu --show-ee-token to display your token for the GraalVM Download Service.

4. Store this token as a GitHub Action secret. In the following template, we use the name GDS_TOKEN:

   name: GraalVM Enterprise Edition build
   on: [push, pull_request]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v6
         - uses: graalvm/setup-graalvm@v1
           with:
             version: '22.3.0'
             gds-token: ${{ secrets.GDS_TOKEN }}
             java-version: '17'
             components: 'native-image'
             github-token: ${{ secrets.GITHUB_TOKEN }}
         - name: Example step
           run: |
             java --version
             native-image --version

Supported distributions

Currently, the following distributions are supported:

Keyword	Distribution	Official site	License
graalvm	Oracle GraalVM	Link	Link
graalvm-community	GraalVM Community Edition	Link	Link
mandrel	Mandrel	Link	Link
liberica	Liberica NIK	Link	Link

Options

This actions can be configured with the following options:

Name	Default	Description
version	''	X.Y (e.g., 25.0, 25.4) for GraalVM releases starting 25.0 25i-latest for the latest GraalVM 25 innovation release X.Y.Z (e.g., 22.3.0) for a specific GraalVM release up to 22.3.2 mandrel-X.Y.Z.W or X.Y.Z.W-Final (e.g., mandrel-21.3.0.0-Final or 21.3.0.0-Final) for a specific Mandrel release, mandrel-latest or latest for the latest Mandrel stable release.
java-version	''	Java version major versions: '25', '21', '17', '11', '8' specific versions: '25.0.3', '21.0.3' early access (EA) builds: '25i5-ea' (requires distribution: 'graalvm') latest EA build: 'latest-ea' (requires distribution: 'graalvm') dev builds: 'dev' (requires distribution: 'graalvm-community')
distribution	'graalvm'	GraalVM distribution (see supported distributions)
java-package	'jdk'	The package type ('jdk' or 'jdk+fx'). Currently applies to Liberica only.
github-token	'${{ github.token }}'	Token for communication with the GitHub API. Please set this to ${{ secrets.GITHUB_TOKEN }} (see templates) to allow the action to authenticate with the GitHub API, which helps reduce rate-limiting issues.
set-java-home	'true'	If set to 'true', instructs the action to set $JAVA_HOME to the path of the GraalVM installation. Overrides any previous action or command that sets $JAVA_HOME.
cache	''	Name of the build platform to cache dependencies. Turned off by default (''). It can also be 'maven', 'gradle', or 'sbt' and works the same way as described in actions/setup-java.
check-for-updates	'true'	Annotate jobs with update notifications, for example when a new GraalVM release is available.
native-image-musl	'false'	If set to 'true', sets up musl to build static binaries with GraalVM Native Image (Linux only). Example usage (be sure to replace uses: ./ with uses: graalvm/setup-graalvm@v1).
native-image-job-reports *)	'false'	If set to 'true', post a job summary containing a Native Image build report.
native-image-pr-reports *)	'false'	If set to 'true', post a comment containing a Native Image build report on pull requests. Requires write permissions for the pull-requests scope.
native-image-pr-reports-update-existing *)	'false'	Instead of posting another comment, update an existing PR comment with the latest Native Image build report. Requires native-image-pr-reports to be true.
native-image-enable-sbom	'false'	If set to 'true', generate a minimal SBOM based on the Native Image static analysis and submit it to GitHub's dependency submission API. This enables the dependency graph feature for dependency tracking and vulnerability analysis. Requires write permissions for the contents scope and the dependency graph to be actived (on by default for public repositories - see how to activate). Only available in Oracle GraalVM for JDK 24 or later.
components	''	Comma-separated list of GraalVM components (e.g., native-image or ruby,nodejs) that will be installed by the GraalVM Updater.
gds-token	'' Download token for the GraalVM Download Service. If a non-empty token is provided, the action will set up Oracle GraalVM (see Oracle GraalVM via GDS template) or GraalVM Enterprise Edition (see GraalVM EE template) via GDS.

*) Make sure that Native Image is used only once per build job. Otherwise, the report is only generated for the last Native Image build.

Contributing

We welcome code contributions. To get started, you will need to sign the Oracle Contributor Agreement (OCA).

Only pull requests from committers that can be verified as having signed the OCA can be accepted.