actions/setup-java v6: What the New Release Changes for CI Java Builds
Set up your GitHub Actions workflow with a specific version of Java.
At a glance
- What is it?
- The v6 release of actions/setup-java adds new distributions, ESM migration, and stricter verification. This review covers what is new, how the action works, and where its limits are.
- Who is it for?
- Adopt v6 if you run Java, Scala, Kotlin, Gradle, Maven, or sbt builds on GitHub Actions and want current distributions, automatic checksum verification, and better caching keys. Do not adopt it if you still rely on AdoptOpenJDK legacy names or run self-hosted runners older than v2.327.1 for v5, and note v6 requires the same runner baseline.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What setup-java actually does on a runner
The action is a GitHub Action written in TypeScript. It installs a requested Java distribution, adds it to PATH, and sets JAVA_HOME. Beyond that, it configures Maven settings.xml, Maven Toolchains, GPG signing inputs, and environment-variable credentials for publishing. It also registers problem matchers for compiler diagnostics and uncaught exceptions. The README lists caching for Maven, Gradle, and sbt dependencies, plus caching of downloaded JDK installations. For a project that only needs java -version, this action is overkill, but for a multi-module Maven build with signing and caching, it replaces several manual steps.
The v6 release: ESM, new distributions, and stricter defaults
Version 6.0.0 was pushed on 2026-08-24. The headline change is migrating the implementation to ESM to support the latest @actions/* packages. That is a maintenance change, not a user-facing feature. More visible is the addition of Oracle OpenJDK, Red Hat Build of OpenJDK, and Liberica Native Image Kit, plus expanded Tencent Kona support through JDK 25. The action now supports java-version: latest, which resolves the newest stable GA release from the distribution's remote metadata. This is useful for projects that want to track the latest release without editing the workflow. The release notes also mention that JDK downloads now automatically verify authoritative checksums, and package signature verification defaults to enabled for Temurin and Microsoft builds. That is a security improvement, but it can break if the vendor's checksum or signature endpoint is temporarily unavailable. The README does not say how to disable signature verification, only that it defaults to enabled.
Migration concerns: renamed inputs and removed distributions
The v6 release renames three inputs so they are not mistaken for secret values: server-username becomes server-username-env-var, server-password becomes server-password-env-var, and gpg-passphrase becomes gpg-passphrase-env-var. Deprecated aliases still work but emit warnings. If you have existing workflows, you will see warnings until you update. More breaking is the removal of legacy AdoptOpenJDK distributions. The README says to use temurin instead of adopt or adopt-hotspot, and semeru instead of adopt-openj9. If your workflow still uses adopt, it will fail on v6. The Maven GPG passphrase handling also changed: it now passes through gpg.passphraseEnvName instead of the deprecated gpg.passphrase server entry. This requires maven-gpg-plugin 3.2.0 or newer. If you use an older plugin version, your signing will break. These are concrete migration steps, not abstract advice.
How to get it running: commands and inputs
The README gives a minimal example: steps: - uses: actions/checkout@v7 - uses: actions/setup-java@v6 with: distribution: temurin java-version: '25' - run: java --version. You can also read the version from a file using java-version-file with .java-version, .tool-versions, or .sdkmanrc. A .sdkmanrc file can also provide the distribution. For custom JDK archives, there is a jdk-file input (renamed from jdkFile in v5). New inputs include force-download: true to bypass the tool cache and do a fresh install, cache-path for custom cache paths, and cache-read-only: true for restore-only caching. The action supports version syntax including JEP 322 multi-field versions like 18.0.1.1. For self-hosted runners, v5 upgraded to Node 24, and the README says runners must use v2.327.1 or later. The v6 notes do not mention a different runner requirement, so assume that baseline still applies.
Caching: what changed and what stays the same
Dependency caching now supports custom paths with cache-path and restore-only operation with cache-read-only. More interesting is the cache key change: it now includes .mvn/extensions.xml and gradle.properties. That prevents stale restores when Maven extensions or Gradle dependency properties change. This is a real fix for a common CI problem where a build restores an old cache and fails. The README also says downloaded JDKs are now cached automatically when cache is set, and you can use cache-jdk to enable or disable it independently. There is also a warm JDK-cached job that can reuse cached release metadata, avoiding vendor API calls while retaining a stale-metadata fallback for vendor outages and rate limits. That is a nice resilience feature, but it means your first run after a JDK version update might use stale metadata. The README does not say how long metadata stays fresh, so you may need to force-download if you suspect staleness.
Limitations and failure modes
The action is not a universal Java installer. It only supports the distributions listed in the README, and it cannot install a JDK that is not in those lists. The v6 release notes mention that invalid boolean values, unsupported distribution/package/platform combinations, and mismatched Maven toolchain ID counts now fail with targeted errors. That is good, but it means you must be precise with your inputs. The action also does not run your build; it only sets up Java and caching. If you need a specific JDK build that is not in the supported list, you will have to use a different approach. Another limitation is the automatic checksum verification. The README says it verifies downloaded archive checksums when a distribution publishes authoritative checksums. If a distribution does not publish them, the action skips verification. That is a gap, though it is not the action's fault. Also, the action does not install Maven or Gradle; it only caches their dependencies. You still need to install the build tool separately.
Alternatives and how they differ
The main alternative is to use a container image that already has Java installed, such as eclipse-temurin or a custom Docker image. With a container, you do not need a setup step; the Java version is baked into the image. That approach is simpler and faster because there is no download step. However, it requires you to rebuild and push an image for every Java version update, and you lose the dynamic version resolution that setup-java offers with java-version: latest. Another alternative is to use the underlying runner's pre-installed Java, which GitHub-hosted runners include. But that version is fixed and may not match your project's requirement. setup-java gives you per-job control without maintaining images. The trade-off is that setup-java adds a download and installation step to every job, which can be slower than a pre-baked image, especially if the JDK is not cached.
Maintenance and licensing
The repository is MIT-licensed, which means you can use and modify it freely, even in commercial workflows. The action is actively maintained, with v6.0.0 pushed on 2026-08-24 and v4.9.1 and v3.14.2 also updated around the same time. That suggests the maintainers are still backporting fixes to older major versions, but the README explicitly deprecates v1 through v4 and urges users to upgrade to v6. The v5 branch is not deprecated but is not the latest. As a user, you should pin to a major version tag like @v6, but be aware that minor updates within v6 can change behavior, as seen in the v6.0.0 release notes. There is no stated support window, so you should test upgrades in a branch before applying them to your main workflow.
Editorial conclusion
Adopt v6 if you run Java, Scala, Kotlin, Gradle, Maven, or sbt builds on GitHub Actions and want current distributions, automatic checksum verification, and better caching keys. Do not adopt it if you still rely on AdoptOpenJDK legacy names or run self-hosted runners older than v2.327.1 for v5, and note v6 requires the same runner baseline. Before upgrading, verify your Maven GPG plugin is at least 3.2.0 if you use GPG signing, and rename any server-username, server-password, or gpg-passphrase inputs to their new env-var names. The action is MIT-licensed and maintained, but the deprecation of v1 through v4 means you should move to v6 or pin a specific v5 patch if you need Node 20 compatibility. The concrete next step is to update your workflow to actions/setup-java@v6 and run a test build with the new inputs to catch any renamed-parameter warnings.
Community notes