Skip to content

Commit 2924169

Browse files
brunoborgesCopilot
brunoborges
and
Copilot
authored
docs: correct README and advanced usage inconsistencies (#1204)
- Fix stale claim that java-version and distribution are always mandatory - Fix security note that claimed no checksum/signature verification exists - Fix jdkfile toolchain example ID (jdkfile_1.6, not Oracle_1.6) - Clarify default toolchain ID derives from the vendor, not the distribution - Drop stale liberica-nik fallback claim; unsupported packages are rejected - Document IBM Semeru and add missing TOC/nav entries - Note that advanced-usage examples target the unreleased v6 on main - Replace retired ubuntu-20.04 runner and fix a heading level Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 955f34f commit 2924169

2 files changed

Lines changed: 42 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ steps:
4646
- Configures Maven `settings.xml`, Maven Toolchains, Maven GPG signing inputs, and environment-variable based credentials for publishing workflows.
4747
- Registers Java problem matchers for compiler diagnostics and uncaught exceptions.
4848
- Caches dependencies for Maven, Gradle, and sbt.
49+
- Caches downloaded JDK installations between jobs.
4950
- Verifies downloaded archive checksums when a distribution publishes authoritative checksums.
5051
- Optionally verifies package signatures for supported distributions.
5152

@@ -142,7 +143,7 @@ steps:
142143
- run: java --version
143144
```
144145

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

147148
## Inputs
148149

@@ -173,7 +174,7 @@ steps:
173174
| `overwrite-settings` | Overwrite an existing `settings.xml`. | `true` |
174175
| `gpg-private-key` | GPG private key to import. | |
175176
| `gpg-passphrase-env-var` | Environment variable name for the GPG private key passphrase. | `GPG_PASSPHRASE` when a key is set |
176-
| `mvn-toolchain-id` | Maven Toolchain ID. When multiple Java versions are installed, the number of IDs must match the number of versions. | `${distribution}_${java-version}` |
177+
| `mvn-toolchain-id` | Maven Toolchain ID. When multiple Java versions are installed, the number of IDs must match the number of versions. | `${vendor}_${java-version}` |
177178
| `mvn-toolchain-vendor` | Maven Toolchain vendor value. | `${distribution}` |
178179
| `show-download-progress` | Keep Maven artifact download and transfer progress in logs. When `false`, the action adds `-ntp` to `MAVEN_ARGS`. | `false` |
179180

@@ -488,13 +489,17 @@ See [advanced usage](docs/advanced-usage.md) for detailed examples:
488489
- [Installing custom Java package types](docs/advanced-usage.md#installing-custom-java-package-type)
489490
- [Package compatibility](docs/advanced-usage.md#package-compatibility)
490491
- [Ensuring the Maven cache is complete](docs/advanced-usage.md#ensuring-the-maven-cache-is-complete-plugin-dependencies)
492+
- [Caching JDK installations](docs/advanced-usage.md#caching-jdk-installations)
493+
- [Platform and architecture compatibility](docs/advanced-usage.md#platform-and-architecture-compatibility)
491494
- [Installing custom Java architecture](docs/advanced-usage.md#installing-custom-java-architecture)
492495
- [Installing a JDK without setting it as default](docs/advanced-usage.md#installing-jdk-without-setting-as-default)
493496
- [Installing Java from a local file](docs/advanced-usage.md#installing-java-from-local-file)
494497
- [Testing against different Java distributions](docs/advanced-usage.md#testing-against-different-java-distributions)
495498
- [Testing against different platforms](docs/advanced-usage.md#testing-against-different-platforms)
496499
- [Publishing using Apache Maven](docs/advanced-usage.md#publishing-using-apache-maven)
500+
- [Apache Maven with a settings path](docs/advanced-usage.md#apache-maven-with-a-settings-path)
497501
- [Maven transfer progress](docs/advanced-usage.md#maven-transfer-progress-download-logs)
502+
- [Java problem matcher](docs/advanced-usage.md#java-problem-matcher-compiler-annotations)
498503
- [Publishing using Gradle](docs/advanced-usage.md#publishing-using-gradle)
499504
- [Hosted tool cache](docs/advanced-usage.md#hosted-tool-cache)
500505
- [Modifying Maven Toolchains](docs/advanced-usage.md#modifying-maven-toolchains)

‎docs/advanced-usage.md‎

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@
55
- [Liberica](#Liberica)
66
- [Liberica Native Image Kit](#Liberica-Native-Image-Kit)
77
- [Microsoft](#Microsoft)
8+
- [IBM Semeru](#IBM-Semeru)
89
- [Amazon Corretto](#Amazon-Corretto)
910
- [Oracle](#Oracle)
11+
- [Oracle OpenJDK](#Oracle-OpenJDK)
1012
- [Alibaba Dragonwell](#Alibaba-Dragonwell)
1113
- [SapMachine](#SapMachine)
1214
- [GraalVM](#GraalVM)
@@ -18,13 +20,16 @@
1820
- [JavaFX Maven project](#JavaFX-Maven-project)
1921
- [Ensuring the Maven cache is complete (plugin dependencies)](#ensuring-the-maven-cache-is-complete-plugin-dependencies)
2022
- [Caching JDK installations](#caching-jdk-installations)
23+
- [Platform and architecture compatibility](#platform-and-architecture-compatibility)
2124
- [Installing custom Java architecture](#Installing-custom-Java-architecture)
2225
- [Installing JDK without setting as default](#Installing-JDK-without-setting-as-default)
2326
- [Installing custom Java distribution from local file](#Installing-Java-from-local-file)
2427
- [Testing against different Java distributions](#Testing-against-different-Java-distributions)
2528
- [Testing against different platforms](#Testing-against-different-platforms)
2629
- [Publishing using Apache Maven](#Publishing-using-Apache-Maven)
30+
- [Apache Maven with a settings path](#apache-maven-with-a-settings-path)
2731
- [Maven transfer progress (download logs)](#Maven-transfer-progress-download-logs)
32+
- [Java problem matcher (compiler annotations)](#java-problem-matcher-compiler-annotations)
2833
- [Publishing using Gradle](#Publishing-using-Gradle)
2934
- [Hosted Tool Cache](#Hosted-Tool-Cache)
3035
- [Modifying Maven Toolchains](#Modifying-Maven-Toolchains)
@@ -33,8 +38,17 @@
3338

3439
See [action.yml](../action.yml) for more details on task inputs.
3540

41+
> [!NOTE]
42+
> The examples on this page reference `actions/setup-java@v6`, which is still in
43+
> development on the `main` branch and is not yet published as a release tag. To
44+
> try the V6 features documented here (`cache-jdk`, `force-download`,
45+
> `problem-matcher`, `cache-path`, `cache-read-only`, `java-version: latest`,
46+
> `oracle-openjdk`, and the `*-env-var` input names), reference
47+
> `actions/setup-java@main`. For production workflows use the latest stable
48+
> release, `actions/setup-java@v5`, as shown in the [README](../README.md).
49+
3650
## Selecting a Java distribution
37-
Inputs `java-version` and `distribution` are mandatory and needs to be provided. See [Supported distributions](../README.md#Supported-distributions) for a list of available options.
51+
`java-version` and `distribution` select what gets installed. `java-version` may be replaced by `java-version-file`, and `distribution` is optional only when `java-version-file` points to a `.sdkmanrc` or `.tool-versions` file that carries a recognized vendor identifier. In every other case both inputs must be provided. See [Supported distributions](../README.md#Supported-distributions) for a list of available options.
3852

3953
### Eclipse Temurin
4054

@@ -117,6 +131,20 @@ with:
117131

118132
If the runner is not able to access github.com, any Java versions requested during a workflow run must come from the runner's tool cache. See "[Setting up the tool cache on self-hosted runners without internet access](https://docs.github.com/en/enterprise-server@3.2/admin/github-actions/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access)" for more information.
119133

134+
### IBM Semeru
135+
**NOTE:** IBM Semeru Runtime Open Edition provides OpenJ9-based builds. Stable releases only; `jdk` and `jre` packages are available.
136+
137+
```yaml
138+
steps:
139+
- uses: actions/checkout@v7
140+
- uses: actions/setup-java@v6
141+
with:
142+
distribution: 'semeru'
143+
java-version: '21'
144+
java-package: jdk # optional (jdk or jre) - defaults to jdk
145+
- run: java --version
146+
```
147+
120148
### Amazon Corretto
121149
**NOTE:** Amazon Corretto only supports the major version specification.
122150

@@ -294,7 +322,7 @@ The package types have these meanings:
294322
| `temurin` | `jdk`, `jre`, `jdk+jmods` | `jdk` and `jre` follow the Adoptium catalog. `jdk+jmods` is available for Java 24 and later and resolves both artifacts at the exact same Java version. |
295323
| `zulu` | `jdk`, `jre`, `jdk+fx`, `jre+fx`, `jdk+crac`, `jre+crac` | Standard JDK builds go back to Java 6; JRE and JavaFX bundles start at Java 8. The vendor catalog has gaps among older non-LTS releases. CRaC bundles start at Java 17 and have more limited OS and architecture availability. |
296324
| `liberica` | `jdk`, `jre`, `jdk+fx`, `jre+fx` | Standard JDK builds go back to Java 8 in the supported action catalog; JRE and JavaFX "full" bundles also start at Java 8. Exact versions follow BellSoft's catalog for the requested platform. |
297-
| `liberica-nik` | `jdk`, `jdk+fx` | `java-version` selects the embedded JDK version, not the NIK/GraalVM release number. BellSoft currently publishes matching standard and JavaFX "full" bundles for JDK 11 and later, with gaps between feature releases. Other values are not meaningful: they resolve to the standard bundle. |
325+
| `liberica-nik` | `jdk`, `jdk+fx` | `java-version` selects the embedded JDK version, not the NIK/GraalVM release number. BellSoft currently publishes matching standard and JavaFX "full" bundles for JDK 11 and later, with gaps between feature releases. Any other `java-package` value is rejected. |
298326
| `microsoft` | `jdk` | Stable builds only. The bundled manifest contains Java 11, 16, 17, 21, and 25 releases; platform availability varies by release. |
299327
| `semeru` | `jdk`, `jre` | Stable OpenJ9 builds only. IBM publishes both image types for the supported release lines (currently 8, 11, 17, 21, and 25), subject to platform availability. |
300328
| `corretto` | `jdk`, `jre` | Accepts major versions only. JDK availability follows Amazon's platform catalog. For the operating systems directly selected by `setup-java`, JRE downloads are limited to Java 8 on Windows; Linux and macOS use `jdk`. |
@@ -678,7 +706,7 @@ steps:
678706
```yaml
679707
jobs:
680708
build:
681-
runs-on: ubuntu-20.04
709+
runs-on: ubuntu-latest
682710
strategy:
683711
matrix:
684712
distribution: [ 'zulu', 'temurin' ]
@@ -694,7 +722,7 @@ jobs:
694722
- run: java --version
695723
```
696724

697-
#### Testing against different platforms
725+
## Testing against different platforms
698726
```yaml
699727
jobs:
700728
build:
@@ -1033,7 +1061,7 @@ The result is a Toolchain with entries for JDKs 8, 11 and 15. You can even combi
10331061
architecture: x64
10341062
```
10351063

1036-
This will generate a Toolchains entry with the following values: `version: 1.6`, `vendor: jdkfile`, `id: Oracle_1.6`.
1064+
This will generate a Toolchains entry with the following values: `version: 1.6`, `vendor: jdkfile`, `id: jdkfile_1.6`.
10371065

10381066
### Modifying The Toolchain Vendor For JDKs
10391067
Each JDK provider will receive a default `vendor` using the `distribution` input value but this can be overridden with the `mvn-toolchain-vendor` parameter as follows.
@@ -1067,7 +1095,7 @@ steps:
10671095
```
10681096

10691097
### Modifying The Toolchain ID For JDKs
1070-
Each JDK provider will receive a default `id` based on the combination of `distribution` and `java-version` in the format of `distribution_java-version` (e.g. `temurin_11`) but this can be overridden with the `mvn-toolchain-id` parameter as follows.
1098+
Each JDK provider will receive a default `id` based on the combination of the toolchain vendor and `java-version` in the format of `vendor_java-version` (e.g. `temurin_11`). The vendor defaults to the `distribution` input, so overriding `mvn-toolchain-vendor` also changes the generated default `id`. Set `mvn-toolchain-id` to override the `id` directly.
10711099

10721100
```yaml
10731101
steps:
@@ -1232,7 +1260,7 @@ On **GitHub Enterprise Server**, traffic from your runners frequently passes thr
12321260

12331261
### Security warning: do not disable certificate verification
12341262

1235-
Do **not** work around this error by disabling TLS verification (for example, by setting `NODE_TLS_REJECT_UNAUTHORIZED=0`). `setup-java` does not verify a pinned checksum or signature of the downloaded archive, so **TLS is effectively the only integrity guarantee** on the JDK download. Disabling verification would expose your workflow to a man-in-the-middle attacker who could serve a tampered JDK — which then becomes the `java` used by the rest of your pipeline, with access to your secrets and credentials. Always extend trust to your CA instead of turning verification off.
1263+
Do **not** work around this error by disabling TLS verification (for example, by setting `NODE_TLS_REJECT_UNAUTHORIZED=0`). Disabling verification would expose your workflow to a man-in-the-middle attacker who could serve a tampered JDK — which then becomes the `java` used by the rest of your pipeline, with access to your secrets and credentials. It also weakens the version metadata requests, which are not checksum-verified at all: a tampered manifest can redirect setup-java to an attacker-controlled download URL. `setup-java` does verify authoritative checksums for [supported distributions](../README.md#download-integrity-and-signatures), and can verify package signatures with `verify-signature: true`, but those checks are not a substitute for a trusted TLS chain. Always extend trust to your CA instead of turning verification off.
12361264

12371265
### Trusting an internal CA inside the installed JDK
12381266

0 commit comments

Comments
 (0)