Setup Java

The setup-java action provides the following functionality for GitHub Actions runners: - Downloading and setting up a requested version of Java. See Usage for a list of supported distributions. - Extracting and caching custom version of Java from a local file. - Configuring runner for publishing using Apache Maven. - Configuring runner for publishing using Gradle. - Configuring runner for using GPG private key. - Registering problem matchers for error output. - Caching dependencies managed by Apache Maven. - Caching dependencies managed by Gradle. - Caching dependencies managed by sbt. - Maven Toolchains declaration for specified JDK versions.

This action allows you to work with Java and Scala projects.

Breaking changes in V5

• Upgraded action from node20 to node24

  Make sure your runner is on version v2.327.1 or later to ensure compatibility with this release Release Notes

For more details, see the full release notes on the releases page

Usage

• java-version: The Java version that is going to be set up. Takes a whole or semver Java version. If not specified, the action will expect java-version-file input to be specified.

• java-version-file: The path to a file containing java version. Supported file types are .java-version and .tool-versions. See more details in about .java-version-file.

• distribution: (required) Java distribution.

• java-package: The packaging variant of the chosen distribution. Possible values: jdk, jre, jdk+fx, jre+fx. Default value: jdk.

• architecture: The target architecture of the package. Possible values: x86, x64, armv7, aarch64, ppc64le. Default value: Derived from the runner machine.

• jdkFile: If a use-case requires a custom distribution setup-java uses the compressed JDK from the location pointed by this input and will take care of the installation and caching on the VM. Note: distribution must be set to 'jdkfile' (case-sensitive; all lowercase) when using this option.

• check-latest: Setting this option makes the action to check for the latest available version for the version spec.

• cache: Quick setup caching for the dependencies managed through one of the predefined package managers. It can be one of "maven", "gradle" or "sbt".

• cache-dependency-path: The path to a dependency file: pom.xml, build.gradle, build.sbt, etc. This option can be used with the cache option. If this option is omitted, the action searches for the dependency file in the entire repository. This option supports wildcards and a list of file names for caching multiple dependencies.

#### Maven options The action has a bunch of inputs to generate maven's settings.xml on the fly and pass the values to Apache Maven GPG Plugin as well as Apache Maven Toolchains. See advanced usage for more.

• overwrite-settings: By default action overwrites the settings.xml. In order to skip generation of file if it exists, set this to false.

• server-id: ID of the distributionManagement repository in the pom.xml file. Default is github.

• server-username: Environment variable name for the username for authentication to the Apache Maven repository. Default is GITHUB_ACTOR.

• server-password: Environment variable name for password or token for authentication to the Apache Maven repository. Default is GITHUB_TOKEN.

• settings-path: Maven related setting to point to the directory where the settings.xml file will be written. Default is ~/.m2.

• gpg-private-key: GPG private key to import. Default is empty string.

• gpg-passphrase: Environment variable name for the GPG private key passphrase. Default is GPG_PASSPHRASE.

• mvn-toolchain-id: Name of Maven Toolchain ID if the default name of ${distribution}_${java-version} is not wanted.

• mvn-toolchain-vendor: Name of Maven Toolchain Vendor if the default name of ${distribution} is not wanted.

Basic Configuration

Eclipse Temurin

steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin' # See 'Supported distributions' for available options
    java-version: '25'
- run: java --version

Azul Zulu OpenJDK

steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: 'zulu' # See 'Supported distributions' for available options
    java-version: '25'
- run: java --version

Supported version syntax

The java-version input supports an exact version or a version range using SemVer notation. The values below are examples, not an exhaustive list: - major versions, such as: 8, 11, 16, 17, 21, 25 - more specific versions: 8.0.282+8, 8.0.232, 11.0, 11.0.4, 17.0 - early access (EA) versions: 15-ea, 15.0.0-ea

Supported distributions

Currently, the following distributions are supported: | Keyword | Distribution / Official site | License |-|-|-| | temurin | Eclipse Temurin | temurin license | zulu | Azul Zulu OpenJDK | zulu license | | adopt or adopt-hotspot | AdoptOpenJDK Hotspot | adopt-hotspot license | | adopt-openj9 | AdoptOpenJDK OpenJ9 | adopt-openj9 license | | liberica | Liberica JDK | liberica license | | microsoft | Microsoft Build of OpenJDK | microsoft license | corretto | Amazon Corretto Build of OpenJDK | corretto license | semeru | IBM Semeru Runtime Open Edition | semeru license | | oracle | Oracle JDK | oracle license | dragonwell | Alibaba Dragonwell JDK | dragonwell license | sapmachine | SAP SapMachine JDK/JRE | sapmachine license | graalvm | Oracle GraalVM | graalvm license | graalvm-community | GraalVM Community | graalvm-community license | jetbrains | JetBrains Runtime | jetbrains license | jdkfile | Custom JDK Installation | |

[!NOTE] - The different distributors can provide discrepant list of available versions / supported configurations. Please refer to the official documentation to see the list of supported versions. - AdoptOpenJDK got moved to Eclipse Temurin and won't be updated anymore. It is highly recommended to migrate workflows from adopt and adopt-openj9, to temurin and semeru respectively, to keep receiving software and security updates. See more details in the Good-bye AdoptOpenJDK post. - For Azul Zulu OpenJDK architectures x64 and arm64 are mapped to x86 / arm with proper hw_bitness. - To comply with the GraalVM Free Terms and Conditions (GFTC) license, it is recommended to use GraalVM JDK 17 version 17.0.12, as this is the only version of GraalVM JDK 17 available under the GFTC license. Additionally, it is encouraged to consider upgrading to GraalVM JDK 21, which offers the latest features and improvements. - GraalVM Community is available as distribution: 'graalvm-community' for stable JDK 17 and later releases published on GitHub.

NOTE: Oracle JDK 17 licensing varies by patch level. As shown on the JDK 17 Archive (versions up to 17.0.12 are under the NFTC license) and the JDK 17.0.13+ Archive (versions 17.0.13 and later are under the OTN license). To stay on the free NFTC license, use distribution: 'oracle' with java-version: '17.0.12' (or earlier) instead of the floating '17'. Alternatively, upgrade to Oracle JDK 21+, which remains under the NFTC license.

NOTE: On Ubuntu runners, commands executed via sudo do not inherit the JAVA_HOME and PATH set by setup-java and will fall back to the runner image's system-default JDK.

Caching packages dependencies

The action has a built-in functionality for caching and restoring dependencies. It uses toolkit/cache under hood for caching dependencies but requires less configuration settings. Supported package managers are gradle, maven and sbt. The format of the used cache key is setup-java-${{ platform }}-${{ packageManager }}-${{ fileHash }}, where the hash is based on the following files:

• gradle: **/*.gradle*, **/gradle-wrapper.properties, buildSrc/**/Versions.kt, buildSrc/**/Dependencies.kt, gradle/*.versions.toml, and **/versions.properties
• maven: **/pom.xml and **/.mvn/wrapper/maven-wrapper.properties
• sbt: all sbt build definition files **/*.sbt, **/project/build.properties, **/project/**.scala, **/project/**.sbt

When the option cache-dependency-path is specified, the hash is based on the matching file. This option supports wildcards and a list of file names, and is especially useful for monorepos.

The workflow output cache-hit is set to indicate if an exact match was found for the key as actions/cache does.

The cache input is optional, and caching is turned off by default.

Caching gradle dependencies

steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '25'
    cache: 'gradle'
    cache-dependency-path: | # optional
      sub-project/*.gradle*
      sub-project/**/gradle-wrapper.properties
- run: ./gradlew build --no-daemon

Using the cache: gradle provides a simple and effective way to cache Gradle dependencies with minimal configuration.

For projects that require more advanced Gradle caching features, such as caching build outputs, support for Gradle configuration cache, encrypted cache storage, fine-grained cache control (including options to enable or disable the cache, set it to read-only or write-only, perform automated cleanup, and define custom cache rules), or optimized performance for complex CI workflows, consider using gradle/actions/setup-gradle.

For setup details and a comprehensive overview of all available features, visit the setup-gradle documentation.

Caching maven dependencies

steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '25'
    cache: 'maven'
    cache-dependency-path: 'sub-project/pom.xml' # optional
- name: Build with Maven
  run: mvn -B package --file pom.xml

Caching sbt dependencies

steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '25'
    cache: 'sbt'
    cache-dependency-path: | # optional
      sub-project/build.sbt
      sub-project/project/build.properties
- name: Build with SBT
  run: sbt package

Cache segment restore timeout

Usually, cache gets downloaded in multiple segments of fixed sizes. Sometimes, a segment download gets stuck, which causes the workflow job to be stuck. The cache segment download timeout was introduced to solve this issue as it allows the segment download to get aborted and hence allows the job to proceed with a cache miss. The default value of the cache segment download timeout is set to 10 minutes and can be customized by specifying an environment variable named SEGMENT_DOWNLOAD_TIMEOUT_MINS with a timeout value in minutes.

```yaml env: SEGMENT_DOWNLOAD_TIMEOUT_MINS: '5' steps: - uses: actions/checkout@v6 - uses: actions/setup-