setup-java with distribution: oracle: licensing and how to switch

Many Java pipelines on GitHub Actions use actions/setup-java, and some of them ask for Oracle's own JDK. That choice was harmless while Oracle JDK 21 was under the No-Fee Terms and Conditions. With the October 2026 change, it becomes the kind of setting that quietly changes what your builds download. This guide explains what the step does and gives replacement YAML.

What distribution: oracle actually downloads

setup-java's Oracle installer builds a download URL from the version you give it. For a major version only, such as '21', it requests https://download.oracle.com/java/21/latest/jdk-21_<os>-<arch>_bin.<ext>; for an exact version it uses the archive path /java/21/archive/jdk-21.0.12_….³ Both are Oracle's "script-friendly" URLs.⁴

The action's own README already warns about the same pattern for JDK 17: Oracle JDK 17 versions up to 17.0.12 are under NFTC and 17.0.13 and later are under OTN, so it recommends pinning '17.0.12' rather than '17'.¹ Oracle stopped serving JDK 17 "latest" URLs in October 2024.⁴

What changes in October 2026

Oracle's roadmap says JDK 21 updates released after September 2026 are planned under the Java SE OTN license,⁵ and Oracle's Java blog says that change starts with the October 2026 Critical Patch Update.⁶ Oracle's script-friendly URL page says the JDK 21 latest URLs cease to work in October 2026.⁴

Is CI "commercial production use"?

The OTN license permits development use: to develop, test, prototype and demonstrate your applications.⁷ Compiling and running tests in a pipeline fits that description. The part to watch is output: a container image with Oracle JDK inside, a jlink runtime assembled from it, or a pipeline that deploys straight to production servers. Those carry Oracle JDK into production, where OTN doesn't grant use. If your pipeline does that, talk to whoever owns your Oracle relationship before deciding it is covered.

Step 1: find every workflow that uses it

# In one repository (skips oracle-openjdk)
$ grep -rnE "distribution:\s*['\"]?oracle['\"]?\s*(#.*)?$" .github/workflows
# Across an organization with the GitHub CLI (review matches by hand)
$ gh search code 'distribution: oracle' --owner YOUR_ORG --extension yml --limit 100

GitHub code search matches text, so oracle-openjdk lines can appear in the organization-wide results; check each match.¹⁰ Also search reusable workflows, composite actions and self-hosted runner images, which can install Oracle JDK outside setup-java.

Step 2: pick a replacement

Option A: an OpenJDK build of the same version (least change)

- uses: actions/setup-java@v6
  with:
    distribution: 'temurin'
    java-version: '21'
    cache: 'maven'

Temurin is provided at no cost to use.¹¹ corretto, zulu or microsoft work the same way. The optional cache input is unchanged by the switch.

Option B: stay on Oracle JDK, move to 25

- uses: actions/setup-java@v6
  with:
    distribution: 'oracle'
    java-version: '25'

Oracle plans NFTC updates for JDK 25 until September 2028.⁹ This is a major-version upgrade for your application, so it needs more testing than Option A, and the same question returns in 2028.

Option C: pin an exact NFTC build (bridge only)

# Short-term bridge only: no Oracle NFTC security fixes after this build
- uses: actions/setup-java@v6
  with:
    distribution: 'oracle'
    java-version: '21.0.12'

A pinned NFTC build keeps its license, but it receives no further Oracle security fixes under NFTC. Whether Oracle keeps serving the archive URL for it isn't documented for JDK 21, so this can break too. Use it for weeks, not years.

oracle-actions/setup-java is a different action

oracle-actions/setup-java is maintained by Oracle and defaults to website: oracle.com, release: 25 and version: latest. Setting website: jdk.java.net installs Oracle's GPL OpenJDK builds instead.⁸ If you use it with release: 21 and the default website, the same October 2026 question applies.

Step 3: check the rest of the pipeline

• Dockerfiles that start FROM container-registry.oracle.com/java/jdk:21 follow the newest JDK 21 update on rebuild.
• Scripts that curl download.oracle.com/java/21/latest/ hit the same retired URL.
• Toolchains: Gradle JvmVendorSpec.ORACLE and Maven <vendor>oracle</vendor> match Oracle JDK and Oracle's OpenJDK builds alike, so check what is installed on the runner.

How RuntimeClear helps

Run the free RuntimeClear scanner with --repo pointed at a checkout and it records each setup-java line with distribution: oracle, Oracle registry image tags, download.oracle.com URLs and Gradle or Maven toolchain vendors, then the report tool classifies them. A floating Oracle JDK 21 reference shows as at risk; the paid report includes the replacement YAML for each one.

Not legal advice. Check your agreements with Oracle for anything specific to your organization.