Setup Java

Set up Java for GitHub Actions workflows. setup-java installs a requested Java distribution, adds it to PATH, configures JAVA_HOME, and can optionally cache build dependencies for Apache Maven, Gradle, and sbt; generate Maven publishing configuration, verify JDK package signatures, manage multiple JDKs, and manage Maven toolchains.

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version: '25'
  - run: java --version

What it does
What’s new
Usage
Inputs
Supported distributions
Supported version syntax
Caching
Multiple JDKs and Maven toolchains
Publishing packages
Advanced usage

What it does

Downloads and installs Java from a supported distribution.
Uses a requested Java version, a version file, or the latest stable release alias.
Extracts and caches a custom JDK archive from a local file.
Configures Maven settings.xml, Maven Toolchains, Maven GPG signing inputs, and environment-variable based credentials for publishing workflows.
Registers Java problem matchers for compiler diagnostics and uncaught exceptions.
Caches dependencies for Maven, Gradle, and sbt.
Caches downloaded JDK installations between jobs.
Verifies downloaded archive checksums when a distribution publishes authoritative checksums.
Optionally verifies package signatures for supported distributions.

setup-java works with Java, Scala, Kotlin, Gradle, Maven, and sbt projects.

What’s new

V6

Migrated the action implementation to ESM to support the latest @actions/* packages.
Added Oracle OpenJDK (oracle-openjdk), Red Hat Build of OpenJDK (redhat), and Liberica Native Image Kit (liberica-nik), and expanded Tencent Kona support through JDK 25.
Added java-version: latest to resolve the newest stable GA release from the distribution’s remote metadata.
Expanded install compatibility with JEP 322 multi-field versions such as 18.0.1.1, Temurin jdk+jmods packages, and native musl artifacts on Alpine for Dragonwell, Corretto, Zulu, and Liberica.
JDK downloads now automatically verify authoritative checksums. Package signature verification is supported for Temurin and Microsoft builds, with configurable strict enforcement.
Added force-download: true to bypass the tool cache and perform a reproducible fresh install.
Dependency caching now supports custom paths with cache-path and restore-only operation with cache-read-only: true.
Dependency cache keys now include .mvn/extensions.xml and gradle.properties, preventing stale restores when Maven extensions or Gradle dependency properties change.
Downloaded JDKs are now cached automatically when cache is set; use cache-jdk to enable or disable it independently.
Warm JDK-cached jobs can reuse cached release metadata, avoiding vendor API calls while retaining a stale-metadata fallback for vendor outages and rate limits.
Maven configuration now supports multiple server credentials and custom dependency-resolution repositories.
Maven signing keys are imported into an isolated temporary GPG home instead of the runner’s default keyring.
Set problem-matcher: false to disable Java compiler and uncaught-exception annotations.
GraalVM distributions now set GRAALVM_HOME in addition to JAVA_HOME.
Invalid boolean values, unsupported distribution/package/platform combinations, and mismatched Maven toolchain ID counts now fail with targeted errors.
Renamed environment-variable-name inputs so they are not mistaken for secret values:
- server-username -> server-username-env-var
- server-password -> server-password-env-var
- gpg-passphrase -> gpg-passphrase-env-var
Deprecated aliases still work, but emit warnings.
Maven GPG passphrases are now passed through gpg.passphraseEnvName instead of a deprecated gpg.passphrase server entry in settings.xml. This requires maven-gpg-plugin 3.2.0 or newer. See GPG.
Legacy AdoptOpenJDK distributions were removed. Use temurin instead of adopt or adopt-hotspot, and semeru instead of adopt-openj9.
See the complete V6 release notes for all enhancements and fixes.

V5

Upgraded the action runtime from Node 20 to Node 24. Self-hosted runners must use version v2.327.1 or later. See the runner release notes.
Added support for GraalVM Community and Tencent Kona.
Expanded java-version-file support with .sdkmanrc files and automatic distribution detection from SDKMAN and asdf vendor identifiers.
Added optional package-signature verification for Eclipse Temurin and Microsoft Build of OpenJDK downloads.
Added set-default: false for installing a JDK without changing JAVA_HOME or PATH.
Improved dependency caching with separate Maven and Gradle wrapper caches, Maven extension-aware cache keys, and the cache-primary-key output.
Improved Maven and Java build behavior by preserving toolchain entries across repeated action invocations, suppressing transfer progress by default, generating non-interactive Maven settings, and matching javac compiler errors.
Renamed the jdkFile input to jdk-file; the old name remains available as a deprecated alias.
See the complete V5 release history for enhancements and fixes across all V5 releases.

Older versions

[!WARNING] actions/setup-java versions v1 through v4 are deprecated. Upgrade workflows to actions/setup-java@v6, the latest stable release.

Usage

Install Eclipse Temurin

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version: '25'
  - run: java --version

Install Microsoft Build of OpenJDK

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: microsoft
      java-version: '25'
  - run: java --version

Read the version from a file

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version-file: .java-version
  - run: java --version

Supported version files are .java-version, .tool-versions, and .sdkmanrc. A .sdkmanrc file can also provide the distribution when it contains a recognized suffix, such as java=21.0.5-tem.

Use the newest stable Java

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version: latest
  - run: java --version

latest resolves the newest stable GA release from remote metadata rather than from the runner tool cache. Distributions that do not publish a release listing (such as oracle and graalvm) resolve the newest GA feature version from the Adoptium available-releases API and then request that version from their own catalog. latest is not supported with java-version-file, early-access versions, or distribution: jdkfile.

Inputs

Input	Description	Default
`java-version`	Java version to install. Supports whole versions, semver ranges, early-access versions, and `latest`. Required unless `java-version-file` is set.
`java-version-file`	Path to `.java-version`, `.tool-versions`, or `.sdkmanrc`. Used when `java-version` is not set.
`distribution`	Java distribution keyword. Values are case-sensitive and must match one of the supported keywords below. Required unless `java-version-file` points to `.sdkmanrc` with a recognized distribution suffix.
`java-package`	Package variant such as `jdk`, `jre`, `jdk+fx`, `jre+fx`, `jdk+crac`, `jre+crac`, `jdk+jmods`, `jdk+jcef`, `jre+jcef`, `jdk+ft`, or `jre+ft`. Support varies by distribution.	`jdk`
`architecture`	Package architecture. Canonical values are `x86`, `x64`, `armv7`, `aarch64`, `ppc64le`, `ppc64`, `riscv64`, and `s390x`. Aliases `ia32`, `amd64`, `arm`, and `arm64` are normalized.	Runner architecture
`jdk-file`	Local compressed JDK archive. Requires `distribution: jdkfile`.
`check-latest`	Check remote metadata for the latest version satisfying the version spec before using the runner tool cache.	`false`
`force-download`	Always download Java and replace any matching version in the tool cache.	`false`
`set-default`	Add Java to `PATH` and set `JAVA_HOME`. When `false`, only version-specific `JAVA_HOME_<major>_<arch>` variables are set.	`true`
`problem-matcher`	Register Java compiler and uncaught exception problem matchers.	`true`
`verify-signature`	Verify downloaded Java package signatures when supported. Explicitly setting this to `true` makes verification failures fatal.	Distribution-dependent; see Download integrity and signatures
`verify-signature-public-key`	One or more ASCII-armored GPG public keys used for signature verification. Concatenate multiple armored key blocks. Custom keys replace the bundled distribution keys.
`token`	Token for fetching GitHub.com-hosted version manifests, useful on GitHub Enterprise Server when unauthenticated requests are rate-limited.	`${{ github.token }}` on GitHub.com; empty string on GHES
`cache`	Enable dependency caching for `maven`, `gradle`, or `sbt`.
`cache-jdk`	Cache downloaded JDK installations between jobs. When omitted, JDK caching is enabled only if `cache` is set. Set explicitly to `true` or `false` to override.	Enabled when `cache` is set
`cache-dependency-path`	Dependency file paths used for cache key hashing. Supports globs and multiline values.	Auto-detected by package manager
`cache-path`	Cache paths to use instead of the package manager’s default dependency cache path. Supports multiline values and exclusions.
`cache-read-only`	Restore dependency, wrapper, and JDK caches without saving changes in the post step.	`false`
`server-id`	Maven repository ID used in generated `settings.xml`.	`github`
`server-username-env-var`	Environment variable name for Maven repository username.	`GITHUB_ACTOR`
`server-password-env-var`	Environment variable name for Maven repository password or token.	`GITHUB_TOKEN`
`mvn-server-credentials`	Multiline Maven server credentials in the format `server-id:USERNAME_ENV:PASSWORD_ENV`. Replaces the single server configured by the three inputs above when set.
`mvn-server-repository-origins`	Multiline Maven credential origins in the format `server-id:repository-origin`. Each origin must belong to a configured server ID. Requires Maven 3.10+.
`mvn-repositories`	Multiline Maven dependency repositories in the format `repository-id:repository-url:snapshots-enabled`.
`mvn-repositories-include-central`	Include Maven Central in the generated dependency repositories profile. When `false`, Central is disabled unless an explicit `central` repository is declared.	`true`
`mvn-repositories-prioritize-central`	Place Maven Central before custom dependency repositories. Has no effect when Maven Central is excluded.	`true`
`settings-path`	Directory where `settings.xml` is written.	`~/.m2`
`overwrite-settings`	Overwrite an existing `settings.xml`.	`true`
`gpg-private-key`	GPG private key to import into an isolated temporary keyring.
`gpg-passphrase-env-var`	Environment variable name for the GPG private key passphrase.	`GPG_PASSPHRASE` when a key is set
`mvn-toolchain-id`	Maven Toolchain ID. When multiple Java versions are installed, the number of IDs must match the number of versions.	`${mvn-toolchain-vendor}_${java-version}`
`mvn-toolchain-vendor`	Maven Toolchain vendor value.	`${distribution}`
`show-download-progress`	Keep Maven artifact download and transfer progress in logs. When `false`, the action adds `-ntp` to `MAVEN_ARGS`.	`false`

java-package: Supported package types are jdk, jre, jdk+fx, jre+fx, jdk+crac, jre+crac, jdk+jmods, jdk+jcef, jre+jcef, jdk+ft, and jre+ft. Availability varies by distribution.

Deprecated aliases jdkFile, server-username, server-password, and gpg-passphrase remain accepted for compatibility, but should be replaced with the current input names.

Outputs

Output	Description
`distribution`	Distribution that was installed.
`version`	Actual Java version that was installed.
`path`	Installation path, also used for `JAVA_HOME` when `set-default` is enabled.
`cache-hit`	Whether an exact dependency cache match was restored.
`cache-primary-key`	Primary cache key computed for the selected package manager. Empty when caching is disabled or skipped.

Supported distributions

Keyword	Distribution	License
`corretto`	Amazon Corretto	License
`dragonwell`	Alibaba Dragonwell JDK	License
`graalvm`	Oracle GraalVM	License
`graalvm-community`	GraalVM Community	License
`jetbrains`	JetBrains Runtime	License
`kona`	Tencent Kona JDK	License
`liberica`	Liberica JDK	License
`liberica-nik`	Liberica Native Image Kit	License
`microsoft`	Microsoft Build of OpenJDK	License
`oracle`	Oracle JDK	License
`oracle-openjdk`	Oracle OpenJDK	License
`redhat`	Red Hat Build of OpenJDK	License
`sapmachine`	SAP SapMachine JDK/JRE	License
`semeru`	IBM Semeru Runtime Open Edition	License
`temurin`	Eclipse Temurin	License
`zulu`	Azul Zulu OpenJDK	License
`jdkfile`	Custom JDK archive

[!NOTE] Distribution availability, package variants, architectures, and version metadata differ by vendor. Check the vendor documentation when a specific version or platform matters.

Additional distribution notes:

Oracle OpenJDK builds are archived after a limited number of releases and no longer receive security updates. To continue receiving security patches, use Oracle JDK or another vendor.
Azul Zulu maps arm64 to aarch64 when querying the Azul Metadata API.
GraalVM Community is available as distribution: graalvm-community for stable JDK 17 and later releases.
On Ubuntu runners, commands executed with sudo do not inherit the JAVA_HOME and PATH set by setup-java and may fall back to the system-default JDK.

Supported version syntax

java-version accepts exact versions, version ranges, early-access versions, and latest.

Syntax	Examples
Major version	`8`, `11`, `17`, `21`, `25`
Specific feature or patch version	`11.0`, `11.0.4`, `17.0`, `8.0.282+8`
JEP 322 multi-field versions	`11.0.9.1`, `18.0.1.1`, `26.0.2.1+1`
Early access	`15-ea`, `15.0.0-ea`, `27-ea`
Latest stable GA release	`latest`

When check-latest is false, the action first tries the runner tool cache for the requested distribution, package type, architecture, and version range. It downloads Java only when no matching cached version is found. When check-latest is true, the action checks remote metadata first and downloads if the cached version is not current.

GitHub-hosted runners primarily pre-cache Eclipse Temurin JDKs. See the installed Java versions for Ubuntu, Windows, and macOS. On a fresh GitHub-hosted runner, requests for other distributions usually miss the tool cache and resolve from remote metadata. For broad version ranges such as a major version (21, 25), this often behaves similarly to check-latest: true because the action downloads the latest available release that satisfies the range.

Download integrity and signatures

setup-java automatically verifies downloaded archive checksums when a selected distribution publishes an authoritative checksum. Automatic checksum verification currently applies to temurin, semeru, corretto, dragonwell, kona, sapmachine, graalvm, graalvm-community, zulu, oracle, oracle-openjdk, microsoft, and jetbrains.

Distributions or individual releases without an authoritative checksum continue to install normally, with the omission reported in debug logs. Installations resolved directly from the runner tool cache — including JDKs preinstalled on the runner image and JDKs installed by an earlier step of the same job — are not downloaded again and are not reverified, even when verify-signature: true is set. Use force-download: true to always download and verify the archive.

Package signature verification is supported for temurin and microsoft. When verify-signature is omitted, the action checks the signature and warns if GPG is unavailable or verification fails, but does not enforce the result. Explicitly setting verify-signature: true enforces verification and makes these failures fatal. Setting verify-signature: true for an unsupported distribution also fails the workflow.

[!WARNING] Requesting explicit signature verification with verify-signature can fail a build after an unexpected but legitimate vendor signing-key rotation, because the action’s bundled keys may not yet include the new key. Confirm a new key through the vendor’s trusted documentation before using it.

After confirming a legitimate rotation, configure the updated key with verify-signature-public-key. The input accepts one or more ASCII-armored public keys; concatenate complete armored key blocks when both old and new vendor keys are needed during a transition. Custom keys replace, rather than extend, the keys bundled with the selected distribution.

- uses: actions/setup-java@v6
  with:
    distribution: temurin
    java-version: '25'
    verify-signature: true
    verify-signature-public-key: |
      -----BEGIN PGP PUBLIC KEY BLOCK-----
      ...vendor key material...
      -----END PGP PUBLIC KEY BLOCK-----

As a temporary fallback while a legitimate rotation is being investigated, set verify-signature: false. This disables package signature verification, although authoritative checksum verification still applies when the vendor publishes a checksum.

- uses: actions/setup-java@v6
  with:
    distribution: temurin
    java-version: '25'
    verify-signature: false

Caching

setup-java manages three kinds of caches. Each one is restored and saved as a separate cache entry.

Cache	What it stores	Key based on	How it is enabled
Dependency cache	Downloaded dependencies, such as `~/.m2/repository`, `~/.gradle/caches`, or the sbt cache paths	Runner OS, architecture, package manager, and a hash of the dependency files	Set `cache` to `maven`, `gradle`, or `sbt`
Wrapper caches	Maven and Gradle wrapper distributions (`~/.m2/wrapper/dists`, `~/.gradle/wrapper`)	Runner OS, architecture, wrapper cache name, and a hash of the wrapper properties	Set `cache` to `maven` or `gradle`
JDK cache	The downloaded JDK installation	Runner OS, architecture, distribution, package type, resolved version, release identity, and signature-verification identity	Enabled implicitly whenever `cache` is set, or explicitly with `cache-jdk: true`. Opt out with `cache-jdk: false`

Set cache to maven, gradle, or sbt to cache dependencies with minimal configuration.

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version: '25'
      cache: maven
  - run: mvn verify

The primary dependency cache key is setup-java-<runner-os>-<node-arch>-<package-manager>-<file-hash>, where <node-arch> is the runner’s Node.js process architecture. The primary cache stores dependency directories such as ~/.m2/repository, ~/.gradle/caches, or the sbt cache paths. Its file hash is based on these files by default:

Package manager	Files used for the primary dependency-cache key
Gradle	`*/.gradle`, `/gradle.properties`, `/gradle-wrapper.properties`, `buildSrc//Versions.kt`, `buildSrc//Dependencies.kt`, `gradle/.versions.toml`, `**/versions.properties`
Maven	`/pom.xml`, `/.mvn/wrapper/maven-wrapper.properties`, `**/.mvn/extensions.xml`
sbt	`*/.sbt`, `/project/build.properties`, `/project/.scala`, `/project/**.sbt`

Use cache-dependency-path to override the files used for key hashing, especially in monorepos:

- uses: actions/setup-java@v6
  with:
    distribution: temurin
    java-version: '25'
    cache: gradle
    cache-dependency-path: |
      sub-project/*.gradle*
      sub-project/**/gradle-wrapper.properties

Use cache-path when the build tool stores dependencies outside the default location:

- uses: actions/setup-java@v6
  with:
    distribution: temurin
    java-version: '25'
    cache: maven
    cache-path: |
      /custom/maven/repository
      !/custom/maven/repository/**/*.lastUpdated
- run: mvn -Dmaven.repo.local=/custom/maven/repository verify

cache-path changes what is restored and saved, but not the cache key. Jobs that should share a cache key must use the same OS, architecture, package manager, dependency files, and cache paths.

Wrapper caches

Maven and Gradle wrapper distributions are restored and saved as additional cache entries, separate from the primary dependency cache. These entries have their own keys in the form setup-java-<runner-os>-<node-arch>-<wrapper-cache-name>-<file-hash>.

Package manager	Wrapper cache name	Cached path	Files used for wrapper-cache key
Maven	`maven-wrapper`	`~/.m2/wrapper/dists`	`**/.mvn/wrapper/maven-wrapper.properties`
Gradle	`gradle-wrapper`	`~/.gradle/wrapper`	`**/gradle-wrapper.properties`

These wrapper caches are independent from dependency caches, so they remain useful even when dependency files change frequently. The wrapper properties are also part of the Maven and Gradle primary dependency-cache key because wrapper changes can affect how dependencies are resolved, but the wrapper distribution files themselves are stored in the separate wrapper cache entries above.

For advanced Gradle caching features such as build output caching, configuration cache support, encrypted cache storage, cleanup, and fine-grained cache control, consider gradle/actions/setup-gradle.

Caching JDK installations

The JDK cache stores the downloaded JDK installation so later runs skip the download. It is enabled implicitly whenever dependency cache is set, so most workflows that cache dependencies are already caching the JDK. Set cache-jdk: true to enable it without dependency caching, or cache-jdk: false to opt out while keeping dependency caching. With neither cache nor cache-jdk set, nothing is cached.

[!IMPORTANT] Because JDK caching is on by default whenever cache is set, review Caching JDK installations for the full cache/cache-jdk matrix, cache identity and storage impact.

Read-only caches

Set cache-read-only: true to restore dependency, wrapper, and JDK caches without saving changes in the post action. This is useful for pull requests, merge queues, short-lived branches, and matrix fan-out jobs that should only consume caches produced elsewhere.

- uses: actions/setup-java@v6
  with:
    distribution: temurin
    java-version: '25'
    cache: maven
    cache-read-only: ${{ github.ref != 'refs/heads/main' }}

For matrix fan-out, seed the cache once and make matrix jobs read-only consumers:

jobs:
  seed-cache:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: '25'
          cache: maven
      - run: mvn dependency:go-offline dependency:resolve-plugins

  build:
    needs: seed-cache
    runs-on: ubuntu-latest
    strategy:
      matrix:
        goal: [test, verify, package]
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: '25'
          cache: maven
          cache-read-only: true
      - run: mvn ${{ matrix.goal }}

Cache segment restore timeout

Cache downloads are split into segments. To reduce the chance of a stuck segment blocking a workflow, set SEGMENT_DOWNLOAD_TIMEOUT_MINS:

env:
  SEGMENT_DOWNLOAD_TIMEOUT_MINS: '5'
steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version: '25'
      cache: gradle
  - run: ./gradlew build --no-daemon

Multiple JDKs and Maven toolchains

Install multiple Java versions by providing a multiline java-version value. All configured JDKs are installed. The last one added to PATH becomes the default.

steps:
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version: |
        8
        11
        17
        21
        25

Other installed JDKs are available through version-specific variables such as JAVA_HOME_17_X64. To use a specific version later in the job, set JAVA_HOME and prepend its bin directory to PATH.

setup-java writes a Maven Toolchains declaration for each installed JDK. When multiple JDKs are installed, the declaration contains all of them. Customize the generated toolchain values with mvn-toolchain-id and mvn-toolchain-vendor.

Testing with a Java matrix

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        java: ['8', '11', '17', '21', '25']
    name: Java ${{ matrix.java }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: ${{ matrix.java }}
      - run: java --version
      - run: mvn verify

Publishing packages

setup-java generates Maven settings.xml and Maven Toolchains configuration. For Gradle publishing, it installs Java for the workflow; the Gradle build file remains responsible for reading credentials from environment variables.

Maven

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version: '25'
      server-id: github
      server-username-env-var: GITHUB_ACTOR
      server-password-env-var: GITHUB_TOKEN
  - run: mvn --batch-mode deploy
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

For dependencies hosted outside Maven Central, use mvn-repositories to add resolution repositories to an active profile in the generated settings.xml. Repository IDs can match mvn-server-credentials IDs when authentication is required. See Resolving Maven dependencies from custom repositories.

GPG signing

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-java@v6
    with:
      distribution: temurin
      java-version: '25'
      gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
      gpg-passphrase-env-var: GPG_PASSPHRASE
  - run: mvn --batch-mode deploy
    env:
      GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}

Maven GPG signing requires maven-gpg-plugin 3.2.0 or newer because setup-java passes the passphrase through gpg.passphraseEnvName.

Recommended permissions

When using the setup-java action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:

permissions:
  contents: read # access to check out code and install dependencies

Publishing workflows may require additional permissions depending on the target registry.

Advanced usage

See advanced usage for detailed examples:

License

The scripts and documentation in this project are released under the MIT License.

Contributions

Contributions are welcome. See our Contributor’s Guide.

Code of Conduct

Be nice. See our code of conduct