Migrate to new Azul metadata API (from Zulu Discovery API)

[StefMa]

Description:
As of today, you're using the Zulu Discover API to fetch available jdks from there:

setup-java/src/distributions/zulu/installer.ts

Line 128 in c5195ef

const availableVersionsUrl = `https://api.azul.com/zulu/download/community/v1.0/bundles/?${requestArguments}`;

According to this documentation, the new Metadata API gets promoted in favor of the old Discovery API.

This change were already announced in the beginning of 2023.

I"m not a zulu employee or something, but I guess it make sense to migrate to the new metadata api before they sunset (if its planned 🤷 ) the old Discovery API.

I just want to make you aware of it as I just found it 🙃

Are you willing to submit a PR?

Not yet

[priya-kinthali]

Hello @StefMa👋,
Thank you for this feature request. We will investigate it and get back to you as soon as we have some feedback.

[brien-crean]

Hey there, I'm seeing failed resolutions when attempting to use actions/setup-java@v5 with Zulu JDK 17, which we use for a React Native project.

Action config:

- name: Set up JDK 17
  uses: actions/setup-java@v5
  with:
    distribution: zulu
    java-version: 17

GH Workflow output

Trying to resolve the latest version from remote
  ##[debug]Gathering available versions from 'https://api.azul.com/zulu/download/community/v1.0/bundles/?os=linux&ext=tar.gz&bundle_type=jdk&javafx=false&arch=x86&hw_bitness=64&release_status=ga'
  Error: Java setup process failed due to: error code: 520

I can reproduce the failure outside GitHub Actions by requesting the same legacy Discovery API endpoint directly:

curl -i 'https://api.azul.com/zulu/download/community/v1.0/bundles/?os=linux&ext=tar.gz&bundle_type=jdk&javafx=false&arch=x86&hw_bitness=64&release_status=ga'
HTTP/2 520 
date: Thu, 28 May 2026 23:02:55 GMT
content-type: text/plain; charset=UTF-8
content-length: 15
cache-control: private, max-age=0, no-store, no-cache, must-revalidate, post-check=0, pre-check=0
expires: Thu, 01 Jan 1970 00:00:01 GMT
referrer-policy: same-origin
x-frame-options: SAMEORIGIN
server: cloudflare
cf-ray: a030e3287aa4c4b4-YVR
alt-svc: h3=":443"; ma=86400

error code: 520%  

Given this issue tracks migration away from the legacy Zulu Discovery API to the newer Azul Metadata API, this looks like a concrete case where the old endpoint is currently breaking CI for distribution: zulu.

Is there a recommended workaround until the Metadata API migration lands in a released actions/setup-java version? For example, should users temporarily pin a specific Zulu archive via jdkFile, use a fork/branch from #998, or wait for a new v5.x release?

[jameswald]

I think this broke today:

Run actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654
Installed distributions
  Trying to resolve the latest version from remote
  Error: Java setup process failed due to: error code: 520
  Error: error code: 520

Workflow file:

      - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'gradle'

[jameswald]

I created #1010 with Claude Sonnet 4.6 to implement https://docs.azul.com/core/detailed/metadata-api-migration.html.

Still need to figure out how to run the tests locally but if someone wants to approve the GitHub action workflows at least we can see how it does there.

Edit: I was able to run the tests, all good.

[brien-crean]

Really appreciate the effort @jameswald! It seems it just started working again. Perhaps it was just a temporary cloudflare issue. I get valid results when requesting from the api link and actions/setup-java@v5 successfully pulled zulu 17 and set it up 🤷

curl -i 'https://api.azul.com/zulu/download/community/v1.0/bundles/?os=linux&ext=tar.gz&bundle_type=jdk&javafx=false&arch=x86&hw_bitness=64&release_status=ga'
HTTP/2 200 
date: Fri, 29 May 2026 05:05:32 GMT
content-type: application/json
last-modified: Fri, 29 May 2026 05:05:32 GMT
cf-cache-status: HIT
vary: accept-encoding
server: cloudflare
cf-ray: a032f6f3e8714ad5-YVR
alt-svc: h3=":443"; ma=86400

[{"java_version":[26,0,1],"jdk_version":[26,0,1,8],"name":"zulu26.30.11-ca-crac-jdk26.0.1-linux_x64.tar.gz","openjdk_build_number":8,"url":"https://cdn.azul.com/zulu/bin/zulu26.30.11-ca-crac-jdk26.0.1-linux_x64.tar.gz","zulu_version":[26,30,11,0]}, ...]

[jameswald]

Yep, all of my CI jobs were failing consistently for a few hours due to this. Once it was back up I was able to successfully retry the failed jobs.

[brunoborges]

Linking implementation: this is being addressed by PR #1010 (Migrate to the new Azul Metadata API). Tracking it there — this issue should auto-close when #1010 merges.