Files
setup-java/README.md

361 lines
26 KiB
Markdown
Raw Normal View History

# Setup Java
2019-07-16 13:28:00 -04:00
2023-01-31 08:48:23 +02:00
[![Basic validation](https://github.com/actions/setup-java/actions/workflows/basic-validation.yml/badge.svg?branch=main)](https://github.com/actions/setup-java/actions/workflows/basic-validation.yml)
[![Validate Java e2e](https://github.com/actions/setup-java/actions/workflows/e2e-versions.yml/badge.svg?branch=main)](https://github.com/actions/setup-java/actions/workflows/e2e-versions.yml)
[![Validate cache](https://github.com/actions/setup-java/actions/workflows/e2e-cache.yml/badge.svg?branch=main)](https://github.com/actions/setup-java/actions/workflows/e2e-cache.yml)
2019-08-12 15:12:48 -04:00
The `setup-java` action provides the following functionality for GitHub Actions runners:
- Downloading and setting up a requested version of Java. See [Usage](#usage) for a list of supported distributions.
2023-01-19 17:52:11 +05:30
- 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](https://maven.apache.org/guides/mini/guide-using-toolchains.html) for specified JDK versions.
This action allows you to work with Java and Scala projects.
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
## What's new in V6
> [!NOTE]
> V6 is still in development (`main` branch) and is not yet recommended for production workflows.
- **Migrated to ESM** to enable support for the latest `@actions/*` package versions. This is an internal implementation change.
Use gpg.passphraseEnvName instead of the deprecated gpg.passphrase server (#1123) * Use gpg.passphraseEnvName instead of gpg.passphrase server The maven-gpg-plugin's `gpg.passphrase`/`passphraseServerId` mechanism is deprecated and fails when the plugin's `bestPractices` mode is enabled. Stop writing the `gpg.passphrase` server to settings.xml and instead set `gpg.passphraseEnvName` via an active profile when the configured passphrase env var name differs from the plugin default (MAVEN_GPG_PASSPHRASE). The default `gpg-passphrase` input value (GPG_PASSPHRASE) is unchanged, so the plugin reads the same environment variable as before. Fixes #760 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Fix settings.xml publishing validation Update the publishing e2e check to assert the settings.xml generated when gpg-passphrase is MAVEN_GPG_PASSPHRASE. In that default case the action no longer writes a gpg.passphrase server entry. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 * Default gpg-passphrase to MAVEN_GPG_PASSPHRASE Align the default `gpg-passphrase` input value with the maven-gpg-plugin default environment variable name (MAVEN_GPG_PASSPHRASE). With this default, setup-java writes no extra GPG configuration to settings.xml and the plugin reads the passphrase from MAVEN_GPG_PASSPHRASE out of the box. Also document that reading the passphrase from an environment variable via `gpg.passphraseEnvName` requires maven-gpg-plugin 3.2.0 or newer. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 * Document gpg-passphrase breaking change in V6 Add a "Breaking changes in V6" section to the README covering the switch to gpg.passphraseEnvName, the new MAVEN_GPG_PASSPHRASE default, and the maven-gpg-plugin 3.2.0+ requirement. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 * Keep GPG_PASSPHRASE default for v5 compatibility Revert the gpg-passphrase input default back to GPG_PASSPHRASE so existing v5 workflows that set the GPG_PASSPHRASE environment variable keep working without changes. setup-java writes gpg.passphraseEnvName=GPG_PASSPHRASE into an active profile, so the maven-gpg-plugin reads the same variable as before. The only remaining compatibility requirement is maven-gpg-plugin 3.2.0+, which is documented in the README and advanced usage guide. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 * Clarify GPG passphrase profile compatibility Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
2026-07-15 10:33:09 -04:00
## Breaking changes in V6
- **Renamed inputs that accept environment-variable names** to make it clear that their values are not credentials. Replace `server-username`, `server-password`, and `gpg-passphrase` with `server-username-env-var`, `server-password-env-var`, and `gpg-passphrase-env-var`, respectively. The old names remain as deprecated aliases and emit a warning when used.
- **The GPG passphrase is now passed to the Maven GPG Plugin through an environment variable (`gpg.passphraseEnvName`) instead of the deprecated `gpg.passphrase` server in `settings.xml`.** Set the environment variable name with `gpg-passphrase-env-var`, which defaults to `GPG_PASSPHRASE`. This requires `maven-gpg-plugin` **3.2.0 or newer**; older versions do not honor `gpg.passphraseEnvName` and, because the `gpg.passphrase` server is no longer written, will not pick up the passphrase. Upgrade the plugin to 3.2.0+.
Use gpg.passphraseEnvName instead of the deprecated gpg.passphrase server (#1123) * Use gpg.passphraseEnvName instead of gpg.passphrase server The maven-gpg-plugin's `gpg.passphrase`/`passphraseServerId` mechanism is deprecated and fails when the plugin's `bestPractices` mode is enabled. Stop writing the `gpg.passphrase` server to settings.xml and instead set `gpg.passphraseEnvName` via an active profile when the configured passphrase env var name differs from the plugin default (MAVEN_GPG_PASSPHRASE). The default `gpg-passphrase` input value (GPG_PASSPHRASE) is unchanged, so the plugin reads the same environment variable as before. Fixes #760 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Fix settings.xml publishing validation Update the publishing e2e check to assert the settings.xml generated when gpg-passphrase is MAVEN_GPG_PASSPHRASE. In that default case the action no longer writes a gpg.passphrase server entry. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 * Default gpg-passphrase to MAVEN_GPG_PASSPHRASE Align the default `gpg-passphrase` input value with the maven-gpg-plugin default environment variable name (MAVEN_GPG_PASSPHRASE). With this default, setup-java writes no extra GPG configuration to settings.xml and the plugin reads the passphrase from MAVEN_GPG_PASSPHRASE out of the box. Also document that reading the passphrase from an environment variable via `gpg.passphraseEnvName` requires maven-gpg-plugin 3.2.0 or newer. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 * Document gpg-passphrase breaking change in V6 Add a "Breaking changes in V6" section to the README covering the switch to gpg.passphraseEnvName, the new MAVEN_GPG_PASSPHRASE default, and the maven-gpg-plugin 3.2.0+ requirement. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 * Keep GPG_PASSPHRASE default for v5 compatibility Revert the gpg-passphrase input default back to GPG_PASSPHRASE so existing v5 workflows that set the GPG_PASSPHRASE environment variable keep working without changes. setup-java writes gpg.passphraseEnvName=GPG_PASSPHRASE into an active profile, so the maven-gpg-plugin reads the same variable as before. The only remaining compatibility requirement is maven-gpg-plugin 3.2.0+, which is documented in the README and advanced usage guide. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 * Clarify GPG passphrase profile compatibility Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d0a510e-aebf-4ec4-a667-efeb3e4edeb1 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
2026-07-15 10:33:09 -04:00
See [GPG](docs/advanced-usage.md#gpg) for details.
## 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](https://github.com/actions/runner/releases/tag/v2.327.1)
For more details, see the full release notes on the [releases page](https://github.com/actions/setup-java/releases/tag/v5.0.0)
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
## Usage
- `java-version`: The Java version that is going to be set up. Takes a whole or [semver](#supported-version-syntax) 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`, `.tool-versions`, and `.sdkmanrc`. See more details in [about .java-version-file](docs/advanced-usage.md#Java-version-file).
- `distribution`: Java [distribution](#supported-distributions). Required unless `java-version-file` points to `.sdkmanrc` with a recognized distribution suffix (for example `java=21.0.5-tem`).
2022-09-22 09:11:15 +02:00
- `java-package`: The packaging variant of the chosen distribution. Possible values: `jdk`, `jre`, `jdk+fx`, `jre+fx`. For Azul Zulu, `jdk+crac` and `jre+crac` are also supported. Default value: `jdk`.
2022-09-22 09:11:15 +02:00
- `architecture`: The target architecture of the package. Possible values: `x86`, `x64`, `armv7`, `aarch64`, `ppc64le`. Default value: Derived from the runner machine.
2022-09-22 09:11:15 +02:00
- `jdk-file`: 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. (The camelCase `jdkFile` input is still accepted as a deprecated alias and may be removed in a future release.)
2022-09-22 09:11:15 +02:00
- `check-latest`: Setting this option makes the action to check for the latest available version for the version spec.
2022-09-22 09:11:15 +02:00
- `set-default`: Set to `false` to install a JDK without making it the default. When `false`, `JAVA_HOME` and `PATH` are not updated, but `JAVA_HOME_<major>_<arch>` is still set so the JDK remains discoverable. Default value: `true`. See [Installing JDK without setting as default](docs/advanced-usage.md#Installing-JDK-without-setting-as-default) for more details.
- `problem-matcher`: Set to `false` to disable Java problem matcher annotations (compiler diagnostics and uncaught exceptions). Default value: `true`. See [Java problem matcher](docs/advanced-usage.md#java-problem-matcher-compiler-annotations) for details and annotation limits.
- `verify-signature`: Verifies downloaded Java package signatures when supported by the selected distribution. Currently supported for `temurin` and `microsoft`. If set to `true` for unsupported distributions, the action fails.
feat: Add verify-signature plumbing and Temurin+Microsoft verification support (#1060) * Add verify-signature plumbing and Temurin verification support * Rebuild dist after signature verification changes * Refine signature verification errors and regenerate dist * refactor: make gpg.ts generic, move Adoptium-specific constant to temurin distribution * fix: mock renameWinArchive in temurin tests and add signature e2e job * refactor: bundle Adoptium public key, replace keyserver lookup with local import * feat: add verify-signature-public-key input to allow custom GPG key override * refactor: extract Adoptium public key to adoptium-key.ts; tighten gpg.ts cleanup scope * Add verify-signature plumbing and Temurin verification support * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Add Microsoft signature verification support * Regenerate dist bundles for Microsoft signature checks * Harden Microsoft signature URL handling * Add setup-java-microsoft-signature-verification e2e job * chore: regenerate dist files * Fix e2e-versions: remove duplicate job, update signature jobs to checkout@v7 with env vars * Fix Prettier formatting in test files * fix: mock renameWinArchive in microsoft-installer tests to fix Windows CI failure * fix: use --homedir flag instead of GNUPGHOME env var for Windows GPG compatibility The Git-bundled GPG on Windows (MSYS2-based) does not automatically convert Windows-style paths in environment variables like GNUPGHOME. This caused GPG to fail with exit code 2 when verifying Microsoft JDK signatures on Windows, because the GNUPGHOME path (D:\a\_temp\...) was not recognized as a valid POSIX path. Fix: pass --homedir as an explicit command-line argument to both gpg --import and gpg --verify. MSYS2 does correctly convert Windows paths in command-line arguments, so this approach works reliably on Windows, Linux, and macOS. * fix: convert Windows paths to POSIX format for MSYS2 GPG on Windows The Git-bundled GPG on Windows (C:\Program Files\Git\usr\bin\gpg.exe) is an MSYS2-based binary that uses POSIX path conventions internally. When Windows-style paths with backslashes and drive letters (D:\a\_temp\...) are passed as arguments, GPG may fail to resolve them correctly, resulting in a fatal error (exit code 2). Fix: add a toGpgPath() helper that converts Windows paths to MSYS2 POSIX format (/d/a/_temp/...) before passing them to any gpg command. On Linux and macOS the helper is a no-op. Applied to all four paths used in verifyPackageSignature: - gpgHome (--homedir argument) - publicKeyFile (--import argument) - signaturePath (--verify signature argument) - archivePath (--verify data argument) * Fix gpg test formatting --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Bruno Borges <brborges@microsoft.com>
2026-06-29 13:19:49 +01:00
- `verify-signature-public-key`: ASCII-armored GPG public key used to verify the downloaded package signature. Overrides the default bundled key for the selected distribution.
feat: Add verify-signature plumbing and Temurin+Microsoft verification support (#1060) * Add verify-signature plumbing and Temurin verification support * Rebuild dist after signature verification changes * Refine signature verification errors and regenerate dist * refactor: make gpg.ts generic, move Adoptium-specific constant to temurin distribution * fix: mock renameWinArchive in temurin tests and add signature e2e job * refactor: bundle Adoptium public key, replace keyserver lookup with local import * feat: add verify-signature-public-key input to allow custom GPG key override * refactor: extract Adoptium public key to adoptium-key.ts; tighten gpg.ts cleanup scope * Add verify-signature plumbing and Temurin verification support * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Add Microsoft signature verification support * Regenerate dist bundles for Microsoft signature checks * Harden Microsoft signature URL handling * Add setup-java-microsoft-signature-verification e2e job * chore: regenerate dist files * Fix e2e-versions: remove duplicate job, update signature jobs to checkout@v7 with env vars * Fix Prettier formatting in test files * fix: mock renameWinArchive in microsoft-installer tests to fix Windows CI failure * fix: use --homedir flag instead of GNUPGHOME env var for Windows GPG compatibility The Git-bundled GPG on Windows (MSYS2-based) does not automatically convert Windows-style paths in environment variables like GNUPGHOME. This caused GPG to fail with exit code 2 when verifying Microsoft JDK signatures on Windows, because the GNUPGHOME path (D:\a\_temp\...) was not recognized as a valid POSIX path. Fix: pass --homedir as an explicit command-line argument to both gpg --import and gpg --verify. MSYS2 does correctly convert Windows paths in command-line arguments, so this approach works reliably on Windows, Linux, and macOS. * fix: convert Windows paths to POSIX format for MSYS2 GPG on Windows The Git-bundled GPG on Windows (C:\Program Files\Git\usr\bin\gpg.exe) is an MSYS2-based binary that uses POSIX path conventions internally. When Windows-style paths with backslashes and drive letters (D:\a\_temp\...) are passed as arguments, GPG may fail to resolve them correctly, resulting in a fatal error (exit code 2). Fix: add a toGpgPath() helper that converts Windows paths to MSYS2 POSIX format (/d/a/_temp/...) before passing them to any gpg command. On Linux and macOS the helper is a no-op. Applied to all four paths used in verifyPackageSignature: - gpgHome (--homedir argument) - publicKeyFile (--import argument) - signaturePath (--verify signature argument) - archivePath (--verify data argument) * Fix gpg test formatting --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Bruno Borges <brborges@microsoft.com>
2026-06-29 13:19:49 +01:00
- `token`: The token used to authenticate when fetching version manifests hosted on GitHub.com. Defaults to `${{ github.token }}` when running on GitHub.com; defaults to an empty string on GitHub Enterprise Server. On GHES, provide a GitHub.com personal access token if manifest requests are rate-limited. See [Using Microsoft distribution on GHES](docs/advanced-usage.md#using-microsoft-distribution-on-ghes) for more details.
- `cache`: Quick [setup caching](#caching-packages-dependencies) for the dependencies managed through one of the predefined package managers. It can be one of "maven", "gradle" or "sbt".
2022-09-22 09:11:15 +02:00
- `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.
2022-09-22 09:11:15 +02:00
#### Maven options
The action has a bunch of inputs to generate maven's [settings.xml](https://maven.apache.org/settings.html) on the fly and pass the values to Apache Maven GPG Plugin as well as Apache Maven Toolchains. See [advanced usage](docs/advanced-usage.md) for more.
2022-09-22 09:11:15 +02:00
- `overwrite-settings`: By default action overwrites the settings.xml. In order to skip generation of file if it exists, set this to `false`.
2022-09-22 09:11:15 +02:00
- `server-id`: ID of the distributionManagement repository in the pom.xml file. Default is `github`.
2022-09-22 09:11:15 +02:00
- `server-username-env-var`: Environment variable name for the username for authentication to the Apache Maven repository. Default is GITHUB\_ACTOR.
2022-09-22 09:11:15 +02:00
- `server-password-env-var`: Environment variable name for password or token for authentication to the Apache Maven repository. Default is GITHUB\_TOKEN.
2022-09-22 09:11:15 +02:00
- `settings-path`: Maven related setting to point to the directory where the settings.xml file will be written. Default is \~/.m2.
2022-09-22 09:11:15 +02:00
- `gpg-private-key`: GPG private key to import. Default is empty string.
2022-09-22 09:11:15 +02:00
- `gpg-passphrase-env-var`: Environment variable name for the GPG private key passphrase. Default is GPG\_PASSPHRASE.
2022-09-22 09:11:15 +02:00
- `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.
- `show-download-progress`: Set to `true` to keep Maven artifact download and transfer progress in build logs. Default value: `false`. By default, the action adds `-ntp` (`--no-transfer-progress`) to `MAVEN_ARGS`. This input has no effect on non-Maven builds. See [Maven transfer progress](docs/advanced-usage.md#maven-transfer-progress-download-logs) for more details.
### Basic Configuration
#### Eclipse Temurin
```yaml
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
with:
distribution: 'temurin' # See 'Supported distributions' for available options
java-version: '25'
- run: java --version
```
#### Azul Zulu OpenJDK
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
```yaml
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
with:
distribution: 'zulu' # See 'Supported distributions' for available options
java-version: '25'
- run: java --version
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
```
2020-05-02 04:33:15 -07:00
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
#### Supported version syntax
The `java-version` input supports an exact version or a version range using [SemVer](https://semver.org/) 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`
- multi-field Java versions (JEP 322), such as: `11.0.9.1`, `18.0.1.1`
- early access (EA) versions: `15-ea`, `15.0.0-ea`
Support pinning java-version as "latest" (#1093) * Support pinning java-version as "latest" Add a `latest` alias for the `java-version` input that floats to the newest available stable (GA) release. It is normalized to the SemVer wildcard at the base-installer layer and always resolves from remote (like `check-latest: true`). List-based distributions resolve it automatically via the existing newest-first matching. Corretto selects its newest available major; Oracle and GraalVM look up the newest GA major via the Adoptium API and request it, failing with an actionable error if that major isn't published yet. The jdkfile distribution rejects `latest`. Closes #832 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Clarify latest note for oracle/graalvm version resolution vs download Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * graalvm-community: float latest to its own newest GA release GraalVM Community publishes its releases on GitHub, so the `latest` alias now matches against that real release list using the SemVer wildcard instead of asking the Adoptium API for the newest GA major. This prevents `latest` from hard-failing when GraalVM lags behind a freshly released Java major (e.g. Adoptium reports 26 before GraalVM ships it). Oracle GraalVM has no listing endpoint, so it keeps deriving the newest major from Adoptium and errors clearly if that major is not yet published. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Give latest+qualifier inputs (e.g. latest-ea) a targeted error Inputs like 'latest-ea' had their '-ea' suffix stripped and fell through to the generic SemVer validation, failing with a confusing "'latest' is not valid SemVer" message even though 'latest' is supported. Add an explicit guard so any 'latest*' value other than exactly 'latest' throws a targeted error explaining that 'latest' resolves GA releases only and cannot be combined with '-ea' or other qualifiers. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
2026-07-09 20:11:03 -04:00
- the `latest` alias, which floats to the newest available stable (GA) release
> [!NOTE]
> - `latest` always resolves the newest version from the distribution's remote metadata (it behaves like `check-latest: true`), so it ignores any older version already present in the runner tool cache. This has the same performance trade-off described in [Check latest](#check-latest).
> - `latest` is only supported through the `java-version` input, not through `java-version-file`, and it resolves stable (GA) releases only — it cannot be combined with `-ea`.
> - The `jdkfile` distribution does not support `latest`, as it installs from a local file.
> - For `oracle` and `graalvm` (Oracle GraalVM), `latest` uses the Adoptium API only to determine the newest GA **major version number** — the JDK binary itself is still downloaded from the Oracle / GraalVM servers for that major. Because these distributions have no endpoint to list their own releases, if their servers haven't published the resolved major yet, the action fails and asks you to specify a concrete version. Note the Oracle JDK license caveat below still applies to a floating `latest`.
> - For `graalvm-community`, `latest` floats to the newest GA release published on GitHub, so it never depends on the Adoptium API and always resolves to the newest major that GraalVM Community actually ships.
2020-05-02 04:33:15 -07:00
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
#### Supported distributions
Currently, the following distributions are supported:
| Keyword | Distribution / Official site | License
|-|-|-|
| `temurin` | [Eclipse Temurin](https://adoptium.net/) | [`temurin` license](https://adoptium.net/about.html)
| `zulu` | [Azul Zulu OpenJDK](https://www.azul.com/downloads/zulu-community/?package=jdk) | [`zulu` license](https://www.azul.com/products/zulu-and-zulu-enterprise/zulu-terms-of-use/) |
| `adopt` or `adopt-hotspot` | [AdoptOpenJDK Hotspot](https://adoptopenjdk.net/) | [`adopt-hotspot` license](https://adoptopenjdk.net/about.html) |
| `adopt-openj9` | [AdoptOpenJDK OpenJ9](https://adoptopenjdk.net/) | [`adopt-openj9` license](https://adoptopenjdk.net/about.html) |
| `liberica` | [Liberica JDK](https://bell-sw.com/) | [`liberica` license](https://bell-sw.com/liberica_eula/) |
| `liberica-nik` | [Liberica Native Image Kit](https://bell-sw.com/pages/downloads/native-image-kit/) | [`liberica-nik` license](https://bell-sw.com/liberica_nik_eula/) |
| `microsoft` | [Microsoft Build of OpenJDK](https://www.microsoft.com/openjdk) | [`microsoft` license](https://docs.microsoft.com/java/openjdk/faq)
| `corretto` | [Amazon Corretto Build of OpenJDK](https://aws.amazon.com/corretto/) | [`corretto` license](https://aws.amazon.com/corretto/faqs/)
| `semeru` | [IBM Semeru Runtime Open Edition](https://developer.ibm.com/languages/java/semeru-runtimes/downloads/) | [`semeru` license](https://openjdk.java.net/legal/gplv2+ce.html) |
| `oracle` | [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) | [`oracle` license](https://java.com/freeuselicense)
| `dragonwell` | [Alibaba Dragonwell JDK](https://dragonwell-jdk.io/) | [`dragonwell` license](https://www.aliyun.com/product/dragonwell/)
| `sapmachine` | [SAP SapMachine JDK/JRE](https://sapmachine.io/) | [`sapmachine` license](https://github.com/SAP/SapMachine/blob/sapmachine/LICENSE)
| `graalvm` | [Oracle GraalVM](https://www.graalvm.org/) | [`graalvm` license](https://www.oracle.com/downloads/licenses/graal-free-license.html)
| `graalvm-community` | [GraalVM Community](https://github.com/graalvm/graalvm-ce-builds/releases) | [`graalvm-community` license](https://github.com/oracle/graal/blob/master/LICENSE)
| `jetbrains` | [JetBrains Runtime](https://github.com/JetBrains/JetBrainsRuntime/) | [`jetbrains` license](https://github.com/JetBrains/JetBrainsRuntime/blob/main/LICENSE)
| `kona` | [Tencent Kona JDK](https://tencent.github.io/konajdk/) | [`kona` license](https://tencent.github.io/konajdk/LICENSE.txt)
| `jdkfile` | Custom JDK Installation | |
2020-05-02 04:33:15 -07:00
> [!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](https://blog.adoptopenjdk.net/2021/08/goodbye-adoptopenjdk-hello-adoptium/).
dist: Migrate from Zulu Discovery API to Azul Metadata API (#1010) * Use Azul metadata API * Document arm64 -> aarch64 mapping in README.md * Paginate through all available versions * Fix typo: win_aarhc4 * Only query for linux_glibc packages * Add Zulu CRaC package support to metadata migration Fold CRaC-related work into the Zulu metadata API migration by wiring crac_supported query handling, extending Zulu package docs, and updating installer tests for jdk+crac/jre+crac behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Harden Zulu metadata pagination with safety cap - Stop paginating on a short page to avoid an extra empty request - Guard against undefined results (not just null) - Cap iterations at 100 pages and warn if the limit is hit to prevent a runaway loop if the API misbehaves Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Preserve JDK build number from Azul Metadata API The Azul Metadata API returns java_version as a 3-element array (e.g. [17,0,7]) and reports the build number separately in openjdk_build_number. The migration mapped version directly from java_version, dropping the build and breaking exact-version lookups like 17.0.7+7 (e2e failure: "No matching version found for SemVer"). Add openjdk_build_number to IZuluVersions and append it to java_version before converting to semver so resolved versions retain the build (e.g. 17.0.7+7). Update the zulu test fixtures to mirror the real API shape (3-element java_version plus openjdk_build_number) so unit tests exercise the actual response format, and rebuild dist. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Bruno Borges <brborges@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-07-08 05:00:43 -04:00
> - For Azul Zulu OpenJDK, architecture `arm64` is mapped to `aarch64` when querying the Azul Metadata API.
> - 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](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) (versions up to 17.0.12 are under the [NFTC](https://www.oracle.com/downloads/licenses/no-fee-license.html) license) and the [JDK 17.0.13+ Archive](https://www.oracle.com/java/technologies/javase/jdk17-0-13-later-archive-downloads.html) (versions 17.0.13 and later are under the [OTN](https://www.oracle.com/downloads/licenses/javase-license1.html) 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.
2021-08-23 11:09:55 +03:00
### Caching packages dependencies
The action has a built-in functionality for caching and restoring dependencies. It uses [toolkit/cache](https://github.com/actions/toolkit/tree/main/packages/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`, `**/.mvn/wrapper/maven-wrapper.properties`, and `**/.mvn/extensions.xml`
2023-04-10 10:56:26 +03:00
- sbt: all sbt build definition files `**/*.sbt`, `**/project/build.properties`, `**/project/**.scala`, `**/project/**.sbt`
2021-08-31 21:42:01 +02:00
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](https://github.com/actions/cache/tree/main#outputs).
The workflow output `cache-primary-key` exposes the primary cache key computed by the action for the configured build tool. It is useful for composing with [`actions/cache`](https://github.com/actions/cache) or [`actions/cache/restore`](https://github.com/actions/cache/tree/main/restore) in later steps or dependent jobs that need to reuse the exact same key. It is empty when caching is not enabled or when caching is skipped (for example, when the cache service is unavailable).
2021-08-31 21:42:01 +02:00
The cache input is optional, and caching is turned off by default.
2021-08-23 11:09:55 +03:00
Cache Maven and Gradle wrapper distributions separately from the dependency cache (#1097) * Cache Maven wrapper distribution separately from the local repository The Maven wrapper distribution (~/.m2/wrapper/dists) was cached in the same entry as the local Maven repository (~/.m2/repository), keyed on a hash of **/pom.xml (plus wrapper properties and extensions). Because pom.xml changes frequently and no restoreKeys are used (by design, #269), almost every change produces a full cache miss and the wrapper distribution is re-downloaded via mvnw — which intermittently fails due to upstream rate limiting. The wrapper distribution only depends on maven-wrapper.properties, which changes very rarely. Give it its own cache entry keyed solely on **/.mvn/wrapper/maven-wrapper.properties so it survives the frequent pom.xml changes that rotate the main dependency cache key. - Add a generic additionalCaches concept to PackageManager, restored and saved independently with name-scoped state keys. - Move ~/.m2/wrapper/dists out of the main maven path into a maven-wrapper additional cache; skip silently when the project does not use mvnw. - Keep cache-hit / cache-primary-key outputs driven by the main cache. - Update tests, docs, and rebuild dist bundles. Fixes #1095 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Cache Gradle wrapper distribution separately from the dependency cache (#1098) The Gradle wrapper distribution (~/.gradle/wrapper) only depends on gradle-wrapper.properties, which changes rarely, but it was previously cached in the same entry as ~/.gradle/caches, keyed on volatile **/*.gradle* files with no restoreKeys (issue #269). Every dependency change therefore re-downloaded the wrapper. Move ~/.gradle/wrapper into a dedicated `gradle-wrapper` additional cache keyed only on **/gradle-wrapper.properties, reusing the additionalCaches infrastructure introduced for the Maven wrapper fix. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Fix broken try/catch in saveAdditionalCache and rebuild dist The autofix commits dropped the `} catch (error) {` line in saveAdditionalCache, leaving a `try` block without a catch and a dangling `error` reference, which broke compilation and Prettier. Restore the catch clause, reformat, and regenerate the dist bundles. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Address cache.ts review feedback - saveAdditionalCache: handle @actions/cache ValidationError (thrown when the cache paths do not resolve, e.g. the wrapper distribution was never downloaded) by skipping instead of failing the post step. Add a test. - Point the Gradle wrapper cache comment at issue #269 (Gradle wrapper cache churn) instead of the Maven-specific #1095. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Document Gradle Wrapper distribution caching in README Add a parallel "Gradle Wrapper" note alongside the Maven Wrapper note, so the new behavior for cache: 'gradle' (caching ~/.gradle/wrapper in a separate entry keyed on **/gradle-wrapper.properties) is documented. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
2026-07-14 17:14:23 -04:00
**Maven Wrapper:** when `cache: 'maven'` is enabled, the action also caches and restores the Maven Wrapper distribution downloaded to `~/.m2/wrapper/dists` (in addition to the local repository), so wrapper-based (`./mvnw`) builds don't re-download the Maven distribution. The wrapper distribution is stored in a **separate** cache entry keyed only on `**/.mvn/wrapper/maven-wrapper.properties`, so it stays cached across the frequent `pom.xml` changes that rotate the main dependency cache key.
2021-08-23 11:09:55 +03:00
#### Caching gradle dependencies
Introduce the dependency caching for Maven and Gradle (#193) * implement a core logic to cache dependnecies * integrate the cache logic to entry points * add a user doc about the dependency cache feature * reflect changes to the dist dir * add a prefix to the cache key https://github.com/actions/setup-java/pull/193/files#r669521434 * test: extract build.gradle to a file in __tests__ dir * run the restore e2e test on the specified OS * add an e2e test for maven * fix the dependency among workflows * stabilize the cache on the Windows in e2e test * add .gitignore files to __tests__/cache directories * try to run restore after the authentication * use the key in state to save caches in the post process * suggest users to run without daemon if fail to save Gradle cache on Windows * add missing description in the README.md * run clean-up tasks in serial * Add validation for post step (#3) * work on fixing cache post step * fix tests * Update src/cleanup-java.ts Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Update src/cache.ts Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * style: put the name of input to the constants.ts * format: run `npm run build` to reflect changes to the dist dir * chore: update licensed files by `licensed cache` it still has three errors as follows: >* setup-java.npm.sax > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/sax.dep.yml > - license needs review: other > >* setup-java.npm.tslib-1.14.1 > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/tslib-1.14.1.dep.yml > - license needs review: 0bsd > >* setup-java.npm.tslib-2.3.0 > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/tslib-2.3.0.dep.yml > - license needs review: 0bsd * fix: rerun ncc on macOS with node v12 * build: follow the suggestion at PR page https://github.com/actions/setup-java/pull/193#issuecomment-901839546 * fix: throw error in case of no package manager file found Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com>
2021-08-20 01:19:35 +08:00
```yaml
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
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
Introduce the dependency caching for Maven and Gradle (#193) * implement a core logic to cache dependnecies * integrate the cache logic to entry points * add a user doc about the dependency cache feature * reflect changes to the dist dir * add a prefix to the cache key https://github.com/actions/setup-java/pull/193/files#r669521434 * test: extract build.gradle to a file in __tests__ dir * run the restore e2e test on the specified OS * add an e2e test for maven * fix the dependency among workflows * stabilize the cache on the Windows in e2e test * add .gitignore files to __tests__/cache directories * try to run restore after the authentication * use the key in state to save caches in the post process * suggest users to run without daemon if fail to save Gradle cache on Windows * add missing description in the README.md * run clean-up tasks in serial * Add validation for post step (#3) * work on fixing cache post step * fix tests * Update src/cleanup-java.ts Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Update src/cache.ts Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * style: put the name of input to the constants.ts * format: run `npm run build` to reflect changes to the dist dir * chore: update licensed files by `licensed cache` it still has three errors as follows: >* setup-java.npm.sax > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/sax.dep.yml > - license needs review: other > >* setup-java.npm.tslib-1.14.1 > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/tslib-1.14.1.dep.yml > - license needs review: 0bsd > >* setup-java.npm.tslib-2.3.0 > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/tslib-2.3.0.dep.yml > - license needs review: 0bsd * fix: rerun ncc on macOS with node v12 * build: follow the suggestion at PR page https://github.com/actions/setup-java/pull/193#issuecomment-901839546 * fix: throw error in case of no package manager file found Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com>
2021-08-20 01:19:35 +08:00
```
2026-01-20 08:16:13 +05:30
Using the `cache: gradle` provides a simple and effective way to cache Gradle dependencies with minimal configuration.
Cache Maven and Gradle wrapper distributions separately from the dependency cache (#1097) * Cache Maven wrapper distribution separately from the local repository The Maven wrapper distribution (~/.m2/wrapper/dists) was cached in the same entry as the local Maven repository (~/.m2/repository), keyed on a hash of **/pom.xml (plus wrapper properties and extensions). Because pom.xml changes frequently and no restoreKeys are used (by design, #269), almost every change produces a full cache miss and the wrapper distribution is re-downloaded via mvnw — which intermittently fails due to upstream rate limiting. The wrapper distribution only depends on maven-wrapper.properties, which changes very rarely. Give it its own cache entry keyed solely on **/.mvn/wrapper/maven-wrapper.properties so it survives the frequent pom.xml changes that rotate the main dependency cache key. - Add a generic additionalCaches concept to PackageManager, restored and saved independently with name-scoped state keys. - Move ~/.m2/wrapper/dists out of the main maven path into a maven-wrapper additional cache; skip silently when the project does not use mvnw. - Keep cache-hit / cache-primary-key outputs driven by the main cache. - Update tests, docs, and rebuild dist bundles. Fixes #1095 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Cache Gradle wrapper distribution separately from the dependency cache (#1098) The Gradle wrapper distribution (~/.gradle/wrapper) only depends on gradle-wrapper.properties, which changes rarely, but it was previously cached in the same entry as ~/.gradle/caches, keyed on volatile **/*.gradle* files with no restoreKeys (issue #269). Every dependency change therefore re-downloaded the wrapper. Move ~/.gradle/wrapper into a dedicated `gradle-wrapper` additional cache keyed only on **/gradle-wrapper.properties, reusing the additionalCaches infrastructure introduced for the Maven wrapper fix. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Fix broken try/catch in saveAdditionalCache and rebuild dist The autofix commits dropped the `} catch (error) {` line in saveAdditionalCache, leaving a `try` block without a catch and a dangling `error` reference, which broke compilation and Prettier. Restore the catch clause, reformat, and regenerate the dist bundles. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Address cache.ts review feedback - saveAdditionalCache: handle @actions/cache ValidationError (thrown when the cache paths do not resolve, e.g. the wrapper distribution was never downloaded) by skipping instead of failing the post step. Add a test. - Point the Gradle wrapper cache comment at issue #269 (Gradle wrapper cache churn) instead of the Maven-specific #1095. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Document Gradle Wrapper distribution caching in README Add a parallel "Gradle Wrapper" note alongside the Maven Wrapper note, so the new behavior for cache: 'gradle' (caching ~/.gradle/wrapper in a separate entry keyed on **/gradle-wrapper.properties) is documented. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
2026-07-14 17:14:23 -04:00
**Gradle Wrapper:** when `cache: 'gradle'` is enabled, the action also caches and restores the Gradle Wrapper distribution downloaded to `~/.gradle/wrapper` (in addition to the Gradle caches), so wrapper-based (`./gradlew`) builds don't re-download the Gradle distribution. The wrapper distribution is stored in a **separate** cache entry keyed only on `**/gradle-wrapper.properties`, so it stays cached across the frequent `*.gradle*` changes that rotate the main dependency cache key.
2026-01-20 08:16:13 +05:30
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`](https://github.com/gradle/actions/tree/main/setup-gradle).
For setup details and a comprehensive overview of all available features, visit the [setup-gradle documentation](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md).
Introduce the dependency caching for Maven and Gradle (#193) * implement a core logic to cache dependnecies * integrate the cache logic to entry points * add a user doc about the dependency cache feature * reflect changes to the dist dir * add a prefix to the cache key https://github.com/actions/setup-java/pull/193/files#r669521434 * test: extract build.gradle to a file in __tests__ dir * run the restore e2e test on the specified OS * add an e2e test for maven * fix the dependency among workflows * stabilize the cache on the Windows in e2e test * add .gitignore files to __tests__/cache directories * try to run restore after the authentication * use the key in state to save caches in the post process * suggest users to run without daemon if fail to save Gradle cache on Windows * add missing description in the README.md * run clean-up tasks in serial * Add validation for post step (#3) * work on fixing cache post step * fix tests * Update src/cleanup-java.ts Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Update src/cache.ts Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * style: put the name of input to the constants.ts * format: run `npm run build` to reflect changes to the dist dir * chore: update licensed files by `licensed cache` it still has three errors as follows: >* setup-java.npm.sax > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/sax.dep.yml > - license needs review: other > >* setup-java.npm.tslib-1.14.1 > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/tslib-1.14.1.dep.yml > - license needs review: 0bsd > >* setup-java.npm.tslib-2.3.0 > filename: /Users/kengo/GitHub/setup-java/.licenses/npm/tslib-2.3.0.dep.yml > - license needs review: 0bsd * fix: rerun ncc on macOS with node v12 * build: follow the suggestion at PR page https://github.com/actions/setup-java/pull/193#issuecomment-901839546 * fix: throw error in case of no package manager file found Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com>
2021-08-20 01:19:35 +08:00
2021-08-23 11:09:55 +03:00
#### Caching maven dependencies
```yaml
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
with:
distribution: 'temurin'
java-version: '25'
cache: 'maven'
cache-dependency-path: 'sub-project/pom.xml' # optional
- name: Build with Maven
run: mvn package --file pom.xml
2021-08-23 11:09:55 +03:00
```
> [!NOTE]
> Maven resolves plugin dependencies lazily, so a cache created by a "thin" goal
> (e.g. `mvn compile`) can be missing plugin dependencies that later
> `test`/`verify`/`package` jobs then re-download on every run. See
> [Ensuring the Maven cache is complete](docs/advanced-usage.md#ensuring-the-maven-cache-is-complete-plugin-dependencies)
> for how to seed a complete cache.
2022-04-20 16:26:27 +02:00
#### Caching sbt dependencies
```yaml
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
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
2022-04-20 16:26:27 +02:00
```
#### 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](https://github.com/actions/toolkit/tree/main/packages/cache#cache-segment-restore-timeout) 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@v7
- uses: actions/setup-java@v6
with:
distribution: 'temurin'
java-version: '25'
cache: 'gradle'
- run: ./gradlew build --no-daemon
```
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
### Check latest
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
In the basic examples above, the `check-latest` flag defaults to `false`. When set to `false`, the action tries to first resolve a version of Java from the local tool cache on the runner. If unable to find a specific version in the cache, the action will download a version of Java. Use the default or set `check-latest` to `false` if you prefer a faster more consistent setup experience that prioritizes trying to use the cached versions at the expense of newer versions sometimes being available for download.
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
If `check-latest` is set to `true`, the action first checks if the cached version is the latest one. If the locally cached version is not the most up-to-date, the latest version of Java will be downloaded. Set `check-latest` to `true` if you want the most up-to-date version of Java to always be used. Setting `check-latest` to `true` has performance implications as downloading versions of Java is slower than using cached versions.
2020-05-02 04:33:15 -07:00
For Java distributions that are not cached on Hosted images, `check-latest` always behaves as `true` and downloads Java on the fly. Check out [Hosted Tool Cache](docs/advanced-usage.md#Hosted-Tool-Cache) for more details about pre-cached Java versions.
2019-07-17 10:56:53 -04:00
```yaml
2019-07-25 21:24:28 -04:00
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
with:
distribution: 'temurin'
java-version: '25'
check-latest: true
- run: java --version
2019-07-17 10:56:53 -04:00
```
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
### Testing against different Java versions
2019-07-17 10:56:53 -04:00
```yaml
jobs:
build:
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
runs-on: ubuntu-20.04
2019-07-17 10:56:53 -04:00
strategy:
matrix:
java: [ '8', '11', '17', '21', '25' ]
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
name: Java ${{ matrix.Java }} sample
2019-07-25 21:24:28 -04:00
steps:
- uses: actions/checkout@v7
2019-07-17 10:56:53 -04:00
- name: Setup java
uses: actions/setup-java@v6
2019-07-17 10:56:53 -04:00
with:
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
distribution: '<distribution>'
2019-08-13 16:24:39 -04:00
java-version: ${{ matrix.java }}
- run: java --version
2019-07-17 10:56:53 -04:00
```
### Install multiple JDKs
2022-09-08 15:26:54 +02:00
All configured Java versions are added to the PATH. The last one added to the PATH (i.e., the last JDK set up by this action) will be used as the default and available globally. Other Java versions can be accessed through environment variables such as 'JAVA\_HOME\_{{ MAJOR\_VERSION }}\_{{ ARCHITECTURE }}'. To use a specific Java version, set the JAVA\_HOME environment variable accordingly and prepend its bin directory to the PATH to ensure it takes priority during execution.
2022-09-08 15:26:54 +02:00
```yaml
steps:
- uses: actions/setup-java@v6
with:
2022-07-15 09:14:25 +02:00
distribution: '<distribution>'
2022-09-08 15:26:54 +02:00
java-version: |
8
11
15
```
### Using Maven Toolchains
In the example above multiple JDKs are installed for the same job. The result after the last JDK is installed is a Maven Toolchains declaration containing references to all three JDKs. The values for `id`, `version`, and `vendor` of the individual Toolchain entries are the given input values for `distribution` and `java-version` (`vendor` being the combination of `${distribution}_${java-version}`) by default.
### Advanced Configuration
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
- [Selecting a Java distribution](docs/advanced-usage.md#Selecting-a-Java-distribution)
- [Eclipse Temurin](docs/advanced-usage.md#Eclipse-Temurin)
- [Adopt](docs/advanced-usage.md#Adopt)
- [Zulu](docs/advanced-usage.md#Zulu)
- [Liberica](docs/advanced-usage.md#Liberica)
- [Liberica Native Image Kit](docs/advanced-usage.md#Liberica-Native-Image-Kit)
- [Microsoft](docs/advanced-usage.md#Microsoft)
- [Amazon Corretto](docs/advanced-usage.md#Amazon-Corretto)
- [Oracle](docs/advanced-usage.md#Oracle)
- [Alibaba Dragonwell](docs/advanced-usage.md#Alibaba-Dragonwell)
- [SapMachine](docs/advanced-usage.md#SapMachine)
- [GraalVM](docs/advanced-usage.md#GraalVM)
- [JetBrains](docs/advanced-usage.md#JetBrains)
- [Tencent Kona](docs/advanced-usage.md#Tencent-Kona)
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
- [Installing custom Java package type](docs/advanced-usage.md#Installing-custom-Java-package-type)
- [Installing custom Java architecture](docs/advanced-usage.md#Installing-custom-Java-architecture)
- [Installing custom Java distribution from local file](docs/advanced-usage.md#Installing-Java-from-local-file)
- [Testing against different Java distributions](docs/advanced-usage.md#Testing-against-different-Java-distributions)
- [Testing against different platforms](docs/advanced-usage.md#Testing-against-different-platforms)
- [Publishing using Apache Maven](docs/advanced-usage.md#Publishing-using-Apache-Maven)
- [Maven transfer progress (download logs)](docs/advanced-usage.md#maven-transfer-progress-download-logs)
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
- [Publishing using Gradle](docs/advanced-usage.md#Publishing-using-Gradle)
- [Hosted Tool Cache](docs/advanced-usage.md#Hosted-Tool-Cache)
- [Modifying Maven Toolchains](docs/advanced-usage.md#Modifying-Maven-Toolchains)
- [Java Version File](docs/advanced-usage.md#Java-version-file)
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
2025-01-16 09:49:13 -05:00
## 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:
```yaml
permissions:
contents: read # access to check out code and install dependencies
```
Merge "v2-preview" branch into "main" (#150) * actions/setup-java@v2 - Support different distributions (#132) * Implement support for custom vendors in setup-java * minor improvements * minor refactoring * Add unit tests and e2e tests * Update documentation for setup-java@v2 release * minor improvements * regenerate dist * fix comments * resolve comments * resolve comments * fix tests * Update README.md Co-authored-by: George Adams <george.adams@microsoft.com> * Apply suggestions from code review Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * fix minor nitpicks * handle 4th digit * pull latest main * Update README.md * rename adoptium to adopt * rename adoptium to adopt * rename adoptium to adopt * Update README.md * make java-version and distribution required for action * update readme * fix tests * fix e2e tests Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Add "overwrite-settings" input parameter (#136) * add overwrite-settings parameter * fix e2e tests * print debug * fix e2e tests * add comment * remove comment * Add "Contents/Home" postfix on macOS if provider creates it (#139) * Update e2e-versions.yml * Update e2e-versions.yml * implement fix * Update e2e-versions.yml * Update installer.ts * fix filter logic * Update e2e-versions.yml * remove extra logic * Update e2e-versions.yml * Add check-latest flag (#141) * add changes for check-latest * run prerelease script * resolving comments * fixing tests * fix spelling * improve core.info messages * run format * run prerelease * change version to fix test * resolve comment for check-latest * Update README.md * added hosted tool cache section * Apply suggestions from code review Co-authored-by: Maxim Lobanov <v-malob@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> * Avoid "+" sign in Java path in v2-preview (#145) * try to handle _ versions * more logs * more debug * test 1 * more fixes * fix typo * Update e2e-versions.yml * add unit-tests * remove debug info from tests * debug pre-cached versions * change e2e tests to ubuntu-latest * update npm licenses Co-authored-by: George Adams <george.adams@microsoft.com> Co-authored-by: Konrad Pabjan <konradpabjan@github.com> Co-authored-by: Dmitry Shibanov <dmitry-shibanov@github.com>
2021-04-05 13:02:27 +03:00
## License
2019-07-17 10:56:53 -04:00
The scripts and documentation in this project are released under the [MIT License](LICENSE).
2019-07-17 10:56:53 -04:00
2022-08-01 01:37:40 +02:00
## Contributions
2019-07-17 10:56:53 -04:00
2022-09-22 15:55:15 +02:00
Contributions are welcome! See [Contributor's Guide](docs/contributors.md)