docs: document importing an internal CA into the installed JDK (cacerts)#1051
Merged
Conversation
Document how to make the installed JDK trust an internal CA at application runtime by importing it into $JAVA_HOME/lib/security/cacerts with keytool after setup-java runs. Clarifies this is the runtime trust layer, distinct from the download/transport layer (NODE_EXTRA_CA_CERTS), and notes hosted vs self-hosted persistence caveats. Refs #640 #1035 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates docs/advanced-usage.md to document how to trust an internal/self-signed CA inside the installed JDK (the cacerts trust store) after actions/setup-java has completed, addressing runtime TLS failures (e.g., PKIX path building errors) that are distinct from download-time TLS issues covered previously.
Changes:
- Adds a new “Trusting an internal CA inside the installed JDK” subsection under the existing self-signed/internal CA documentation.
- Provides a post-install
keytool -importcertworkflow example targeting$JAVA_HOME/lib/security/cacerts. - Adds caveats about
cacertspassword, hosted vs self-hosted persistence, and alias/idempotency behavior.
Show a summary per file
| File | Description |
|---|---|
| docs/advanced-usage.md | Adds guidance and an example for importing an internal CA into the installed JDK’s cacerts trust store after setup-java. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 1
| - The default keystore password for `cacerts` is `changeit` unless your distribution overrides it. | ||
| - 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. | ||
| - 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. | ||
| - 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). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Follow-up to #1050. Adds a "Trusting an internal CA inside the installed JDK" subsection to the self-signed certificate / internal CA docs in
docs/advanced-usage.md.Why
#1050 documented the download/transport layer (making the runner trust the CA via
NODE_EXTRA_CA_CERTSso the JDK can be downloaded). That's separate from the JDK runtime layer: once installed, thejavaruntime has its owncacertskeystore, and builds that call internal HTTPS endpoints fail with:This subsection closes that gap.
What it covers
$JAVA_HOME/lib/security/cacerts), independent of the OS/Node trust stores.keytool -importcertexample that runs afteractions/setup-java(soJAVA_HOMEpoints at the freshly installed JDK).changeitkeystore password, hosted vs self-hosted persistence, idempotent aliasing.cacertsfile — the post-install step covers it.Notes
dist/changes.prettier --checkpasses.Closes #1035