Skip to content

Commit c5d316e

Browse files
brunoborgesbrunoborges
authored
Merge branch 'main' into patch-1
2 parents 7d4c734 + 668c1ea commit c5d316e

2 files changed

Lines changed: 141 additions & 24 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ steps:
7676
with:
7777
distribution: 'temurin' # See 'Supported distributions' for available options
7878
java-version: '25'
79-
- run: java HelloWorldApp.java
79+
- run: java --version
8080
```
8181
8282
#### Azul Zulu OpenJDK
@@ -87,7 +87,7 @@ steps:
8787
with:
8888
distribution: 'zulu' # See 'Supported distributions' for available options
8989
java-version: '25'
90-
- run: java HelloWorldApp.java
90+
- run: java --version
9191
```
9292
9393
#### Supported version syntax
@@ -221,7 +221,7 @@ steps:
221221
distribution: 'temurin'
222222
java-version: '25'
223223
check-latest: true
224-
- run: java HelloWorldApp.java
224+
- run: java --version
225225
```
226226

227227
### Testing against different Java versions
@@ -240,7 +240,7 @@ jobs:
240240
with:
241241
distribution: '<distribution>'
242242
java-version: ${{ matrix.java }}
243-
- run: java HelloWorldApp.java
243+
- run: java --version
244244
```
245245

246246
### Install multiple JDKs

‎docs/advanced-usage.md‎

Lines changed: 137 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
- [GraalVM](#GraalVM)
1313
- [JetBrains](#JetBrains)
1414
- [Installing custom Java package type](#Installing-custom-Java-package-type)
15+
- [JavaFX Maven project](#JavaFX-Maven-project)
1516
- [Installing custom Java architecture](#Installing-custom-Java-architecture)
1617
- [Installing custom Java distribution from local file](#Installing-Java-from-local-file)
1718
- [Testing against different Java distributions](#Testing-against-different-Java-distributions)
@@ -21,6 +22,7 @@
2122
- [Hosted Tool Cache](#Hosted-Tool-Cache)
2223
- [Modifying Maven Toolchains](#Modifying-Maven-Toolchains)
2324
- [Java-version file](#Java-version-file)
25+
- [Self-signed certificates and internal CAs (GitHub Enterprise)](#Self-signed-certificates-and-internal-CAs-GitHub-Enterprise)
2426

2527
See [action.yml](../action.yml) for more details on task inputs.
2628

@@ -36,7 +38,7 @@ steps:
3638
with:
3739
distribution: 'temurin'
3840
java-version: '21'
39-
- run: java -cp java HelloWorldApp
41+
- run: java --version
4042
```
4143
4244
### Adopt
@@ -49,7 +51,7 @@ steps:
4951
with:
5052
distribution: 'adopt-hotspot'
5153
java-version: '11'
52-
- run: java -cp java HelloWorldApp
54+
- run: java --version
5355
```
5456

5557
### Zulu
@@ -62,7 +64,7 @@ steps:
6264
distribution: 'zulu'
6365
java-version: '21'
6466
java-package: jdk # optional (jdk, jre, jdk+fx or jre+fx) - defaults to jdk
65-
- run: java -cp java HelloWorldApp
67+
- run: java --version
6668
```
6769

6870
### Liberica
@@ -75,7 +77,7 @@ steps:
7577
distribution: 'liberica'
7678
java-version: '21'
7779
java-package: jdk # optional (jdk, jre, jdk+fx or jre+fx) - defaults to jdk
78-
- run: java -cp java HelloWorldApp
80+
- run: java --version
7981
```
8082

8183
### Microsoft
@@ -87,7 +89,7 @@ steps:
8789
with:
8890
distribution: 'microsoft'
8991
java-version: '21'
90-
- run: java -cp java HelloWorldApp
92+
- run: java --version
9193
```
9294

9395
### Using Microsoft distribution on GHES
@@ -116,7 +118,7 @@ steps:
116118
with:
117119
distribution: 'corretto'
118120
java-version: '21'
119-
- run: java -cp java HelloWorldApp
121+
- run: java --version
120122
```
121123

122124
### Oracle
@@ -129,7 +131,7 @@ steps:
129131
with:
130132
distribution: 'oracle'
131133
java-version: '21'
132-
- run: java -cp java HelloWorldApp
134+
- run: java --version
133135
```
134136

135137
### Alibaba Dragonwell
@@ -142,7 +144,7 @@ steps:
142144
with:
143145
distribution: 'dragonwell'
144146
java-version: '8'
145-
- run: java -cp java HelloWorldApp
147+
- run: java --version
146148
```
147149

148150
### SapMachine
@@ -154,7 +156,7 @@ steps:
154156
with:
155157
distribution: 'sapmachine'
156158
java-version: '21'
157-
- run: java -cp java HelloWorldApp
159+
- run: java --version
158160
```
159161

160162
### GraalVM
@@ -168,8 +170,8 @@ steps:
168170
distribution: 'graalvm'
169171
java-version: '21'
170172
- run: |
171-
java -cp java HelloWorldApp
172-
native-image -cp java HelloWorldApp
173+
java --version
174+
native-image --version
173175
```
174176

175177
### JetBrains
@@ -186,7 +188,7 @@ steps:
186188
with:
187189
distribution: 'jetbrains'
188190
java-version: '11'
189-
- run: java -cp java HelloWorldApp
191+
- run: java --version
190192
```
191193

192194
The JetBrains installer uses the GitHub API to fetch the latest version. If you believe your project is going to be running into rate limits, you can provide a
@@ -202,7 +204,7 @@ steps:
202204
java-package: 'jdk' # optional (jdk, jre, jdk+jcef, jre+jcef, jdk+ft, or jre+ft) - defaults to jdk
203205
env:
204206
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
205-
- run: java -cp java HelloWorldApp
207+
- run: java --version
206208
```
207209

208210
You can specify your package type (as shown in the [releases page](https://github.com/JetBrains/JetBrainsRuntime/releases/)) in the `java-package` parameter.
@@ -225,7 +227,31 @@ steps:
225227
distribution: '<distribution>'
226228
java-version: '11'
227229
java-package: jdk # optional (jdk or jre) - defaults to jdk
228-
- run: java -cp java HelloWorldApp
230+
- run: java --version
231+
```
232+
233+
### JavaFX Maven project
234+
235+
For JavaFX projects that use Maven, use `jdk+fx` (or `jre+fx`) as the `java-package` value together with a distribution that supports it (e.g. `zulu` or `liberica`). Then include the [`javafx-maven-plugin`](https://openjfx.io/openjfx-docs/#maven) in your `pom.xml` as described in the [Getting Started with JavaFX](https://openjfx.io/openjfx-docs/#maven) guide.
236+
237+
```yaml
238+
steps:
239+
- uses: actions/checkout@v6
240+
- uses: actions/setup-java@v5
241+
with:
242+
distribution: 'zulu'
243+
java-version: '21'
244+
java-package: jdk+fx
245+
cache: maven
246+
- name: Build with Maven
247+
run: mvn --no-transfer-progress compile
248+
```
249+
250+
To run the JavaFX application in CI:
251+
252+
```yaml
253+
- name: Run with Maven
254+
run: mvn --no-transfer-progress javafx:run
229255
```
230256

231257
## Installing custom Java architecture
@@ -238,7 +264,7 @@ steps:
238264
distribution: '<distribution>'
239265
java-version: '11'
240266
architecture: x86 # optional - default value derived from the runner machine
241-
- run: java -cp java HelloWorldApp
267+
- run: java --version
242268
```
243269

244270
## Installing Java from local file
@@ -256,7 +282,7 @@ steps:
256282
java-version: '11.0.0'
257283
architecture: x64
258284
259-
- run: java -cp java HelloWorldApp
285+
- run: java --version
260286
```
261287

262288
If your use-case requires a custom distribution (in the example, alpine-linux is used) or a version that is not provided by setup-java and you want to always install the latest version during runtime, then you can use the following code to auto-download the latest JDK, determine the semver needed for setup-java, and setup-java will take care of the installation and caching on the VM:
@@ -281,7 +307,7 @@ If your use-case requires a custom distribution (in the example, alpine-linux is
281307
jdkFile: ${{ runner.temp }}/java_package.tar.gz
282308
java-version: {{ steps.fetch_latest_jdk.outputs.java_version }}
283309
architecture: x64
284-
- run: java -cp java HelloWorldApp
310+
- run: java --version
285311
```
286312

287313
## Testing against different Java distributions
@@ -302,7 +328,7 @@ jobs:
302328
with:
303329
distribution: ${{ matrix.distribution }}
304330
java-version: ${{ matrix.java }}
305-
- run: java -cp java HelloWorldApp
331+
- run: java --version
306332
```
307333

308334
#### Testing against different platforms
@@ -322,7 +348,7 @@ jobs:
322348
with:
323349
distribution: 'temurin'
324350
java-version: ${{ matrix.java }}
325-
- run: java -cp java HelloWorldApp
351+
- run: java --version
326352
```
327353

328354
## Publishing using Apache Maven
@@ -560,7 +586,7 @@ steps:
560586
distribution: 'temurin'
561587
java-version: '11'
562588
mvn-toolchain-id: 'some_other_id'
563-
- run: java -cp java HelloWorldApp
589+
- run: java --version
564590
```
565591

566592
In case you install multiple versions of Java at once you can use the same syntax as used in `java-versions`. Please note that you have to declare an ID for all Java versions that will be installed or the `mvn-toolchain-id` instruction will be skipped wholesale due to mapping ambiguities.
@@ -615,3 +641,94 @@ If the file contains multiple versions, only the first one will be recognized.
615641
616642
***NOTE***:
617643
For the tool-version file, ensure that you use standard semantic versioning (semver) formats, as non-standard formats (such as jetbrains-21b212.1) may not be parsed correctly. Additionally, for complex version strings containing multiple version-like segments (for example, java semeru-openj9-11.0.15+10_openj9-0.32.0), the extraction logic may incorrectly capture the last segment (0.32.0) instead of the main version (11.0.15+10).
644+
645+
## Self-signed certificates and internal CAs (GitHub Enterprise)
646+
647+
When `setup-java` dynamically downloads a JDK, it makes HTTPS requests both to fetch the available version metadata and to download the JDK archive. If your runners sit behind a **TLS-inspecting corporate proxy**, or you are on **GitHub Enterprise Server (GHES)** with an internal certificate authority, those requests can fail with an error such as:
648+
649+
```
650+
Error: self signed certificate in certificate chain
651+
```
652+
653+
This happens because the certificate presented to the runner is signed by an **internal or self-signed CA** that is not part of the runner's default trust store. The download itself is fine — the runner simply cannot verify the certificate chain.
654+
655+
### Recommended fix: trust your internal CA
656+
657+
The secure way to resolve this is to make the runner trust your organization's CA, which keeps TLS verification fully enabled. `setup-java` runs on Node.js, which honors the [`NODE_EXTRA_CA_CERTS`](https://nodejs.org/api/cli.html#node_extra_ca_certsfile) environment variable. Point it at your CA bundle (in PEM format) **before** the `actions/setup-java` step:
658+
659+
```yaml
660+
steps:
661+
# The CA bundle is already present on the runner image in this example.
662+
# Alternatively, write it from a secret in a previous step.
663+
- name: Trust the internal CA
664+
run: echo "NODE_EXTRA_CA_CERTS=/etc/ssl/certs/internal-ca.pem" >> "$GITHUB_ENV"
665+
666+
- uses: actions/setup-java@v5
667+
with:
668+
distribution: 'temurin'
669+
java-version: '21'
670+
```
671+
672+
If you keep the certificate in a secret rather than on the runner image, write it to disk first:
673+
674+
```yaml
675+
steps:
676+
- name: Write and trust the internal CA
677+
run: |
678+
echo "${{ secrets.INTERNAL_CA_PEM }}" > "${RUNNER_TEMP}/internal-ca.pem"
679+
echo "NODE_EXTRA_CA_CERTS=${RUNNER_TEMP}/internal-ca.pem" >> "$GITHUB_ENV"
680+
681+
- uses: actions/setup-java@v5
682+
with:
683+
distribution: 'temurin'
684+
java-version: '21'
685+
```
686+
687+
For **self-hosted runners**, you can instead install your CA into the operating system's trust store (for example, `update-ca-certificates` on Debian/Ubuntu or `update-ca-trust` on RHEL). This makes the certificate trusted for all tooling on the runner, not just `setup-java`.
688+
689+
### GitHub Enterprise customers
690+
691+
On **GitHub Enterprise Server**, traffic from your runners frequently passes through an organization-managed proxy or terminates TLS at an appliance using a certificate from an internal CA. If your workflows hit the error above, set `NODE_EXTRA_CA_CERTS` to your enterprise CA bundle (or bake the CA into your self-hosted runner image) as shown above. Coordinate with your platform team to obtain the correct PEM bundle for your appliance and proxy chain.
692+
693+
### Security warning: do not disable certificate verification
694+
695+
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.
696+
697+
### Trusting an internal CA inside the installed JDK
698+
699+
The guidance above makes the **runner** trust your CA so that the JDK can be *downloaded*. That is a separate layer from making the **installed JDK** trust your CA at *application runtime*. If your build steps (Maven/Gradle dependency resolution, integration tests, HTTPS calls from your app, etc.) connect to internal services that present a certificate from your internal CA, the JDK will reject them with errors such as:
700+
701+
```
702+
PKIX path building failed: unable to find valid certification path to requested target
703+
```
704+
705+
The JDK keeps its own trust store — a keystore named `cacerts` under `$JAVA_HOME/lib/security/cacerts` — which is independent of the operating system and Node trust stores. After `setup-java` has run (so that `JAVA_HOME` points at the freshly installed JDK), import your CA into that keystore with `keytool`:
706+
707+
```yaml
708+
steps:
709+
- uses: actions/setup-java@v5
710+
with:
711+
distribution: 'temurin'
712+
java-version: '21'
713+
714+
- name: Import internal CA into the JDK trust store
715+
shell: bash
716+
run: |
717+
# Write the CA from a secret (or reference a file already on the runner)
718+
echo "${{ secrets.INTERNAL_CA_PEM }}" > "${RUNNER_TEMP}/internal-ca.pem"
719+
keytool -importcert -noprompt \
720+
-alias internal-ca \
721+
-file "${RUNNER_TEMP}/internal-ca.pem" \
722+
-keystore "${JAVA_HOME}/lib/security/cacerts" \
723+
-storepass changeit
724+
```
725+
726+
Notes and caveats:
727+
728+
- The default keystore password for `cacerts` is `changeit` unless your distribution overrides it.
729+
- On **hosted runners** the change applies only to the current job's JDK and is discarded when the job ends, so include the import step in every job that needs it.
730+
- On **self-hosted runners**, importing into a tool-cache JDK persists for as long as that cached version remains on the runner; if you want it to survive JDK reinstalls, pre-seed the CA into your runner image or re-run the import step each time.
731+
- Prefer giving the certificate a stable, descriptive `-alias` so re-runs are idempotent (re-importing the same alias will fail; add `keytool -delete -alias internal-ca ...` first if you re-run within a long-lived runner).
732+
733+
This documents the post-install workflow; there is no dedicated action input for supplying a custom `cacerts` file.
734+

0 commit comments

Comments
 (0)