Migrate from Zulu Discovery API to Azul Metadata API by jameswald · Pull Request #1010 · actions/setup-java

jameswald · 2026-05-29T00:30:42Z

Used Claude Sonnet 4.6 to implement https://docs.azul.com/core/detailed/metadata-api-migration.html. If it's way off the mark then we can close it but if it's salvageable then please feel free to push any necessary commits on top of what is already done.

Summary

Migrates the zulu distribution from the deprecated Zulu Discovery API (https://api.azul.com/zulu/download/community/v1.0/bundles/) to the new Azul Metadata API (https://api.azul.com/metadata/v1/zulu/packages/).

Background

The old Zulu Discovery API was returning HTTP 520 errors for a few hours, breaking all distribution: zulu workflows. Since the beginning of 2023 Azul has recommended the Metadata API and published a migration guide.

Changes

`src/distributions/zulu/models.ts`

Updated IZuluVersions to match the new API response shape:

id: number → package_uuid: string
url → download_url
jdk_version → java_version
zulu_version → distro_version
Added latest: boolean and availability_type: string

`src/distributions/zulu/installer.ts`

New API base URL: https://api.azul.com/metadata/v1/zulu/packages/
Renamed query parameters: ext → archive_type, bundle_type → java_package_type, javafx → javafx_bundled
Removed hw_bitness and abi query parameters (no longer part of the API)
Added availability_types=ca to restrict to free community builds
Pagination: the new API is paginated; added a loop that iterates through all pages until an empty page is returned
Simplified getArchitectureOptions(): now returns a plain string instead of {arch, hw_bitness, abi}. Architecture mapping: x64 → x64, x86 → x86, arm64/aarch64 → aarch64
Linux platform: returns linux_glibc instead of linux to exclude musl packages, which standard GitHub-hosted runners do not use
Fixed a typo: win_aarhc4 → win_aarch64

`README.md`

Updated the architecture-mapping note to reflect the new API's conventions (arm64 → aarch64).

Test fixtures and tests

Updated all three fixture files (zulu-releases-default.json, zulu-linux.json, zulu-windows.json) to use the new field names
Updated URL assertions in all three installer test files to match the new endpoint and parameter names
Updated getArchitectureOptions test cases to expect strings instead of objects
Removed the DistroArch type (no longer needed)

Related issue

Fixes #795

Check list

Documentation updated (README.md)
Tests added/updated to cover the changes

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Migrates the Zulu (Azul) distribution from the deprecated zulu/download/community/v1.0 API to the new metadata/v1/zulu/packages API, updating request parameters, response model fields, and architecture mapping accordingly.

Changes:

Switched API endpoint and renamed query parameters (e.g., ext → archive_type, bundle_type → java_package_type, javafx → javafx_bundled); replaced hw_bitness/abi with a single arch value and added availability_types, page, page_size parameters.
Updated IZuluVersions model to use new field names (package_uuid, download_url, java_version, distro_version, latest, availability_type).
Updated tests and fixture data to align with the new API contract; updated README note about arch mapping.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/distributions/zulu/models.ts	Updated `IZuluVersions` interface to new Azul Metadata API schema.
src/distributions/zulu/installer.ts	Updated request URL/params, response field references, and simplified `getArchitectureOptions` to return a single string.
tests/distributors/zulu-installer.test.ts	Updated expected URLs and arch mapping assertions for macOS.
tests/distributors/zulu-linux-installer.test.ts	Updated expected URLs and arch mapping for Linux.
tests/distributors/zulu-windows-installer.test.ts	Updated expected URLs and arch mapping for Windows.
tests/data/zulu-windows.json	Regenerated fixture to match new API response schema.
tests/data/zulu-linux.json	Regenerated fixture to match new API response schema.
tests/data/zulu-releases-default.json	Regenerated fixture to match new API response schema.
README.md	Updated note about Zulu architecture mapping.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

jameswald · 2026-05-29T01:23:11Z

+      `archive_type=${extension}`,
+      `java_package_type=${bundleType}`,
+      `javafx_bundled=${javafx}`,
      `arch=${arch}`,
-      `hw_bitness=${hw_bitness}`,
      `release_status=${releaseStatus}`,
-      abi ? `abi=${abi}` : null,
-      features ? `features=${features}` : null
-    ]
-      .filter(Boolean)
-      .join('&');
+      `availability_types=ca`,
+      `page=1`,
+      `page_size=1000`
+    ].join('&');


This is beyond me so here's what Claude output in response to this comment:

⏺ The live API response tells the full story. All 5 results with javafx_bundled=true have -fx- in their filenames (e.g., zulu26.30.11-ca-fx-jdk26.0.1-linux_x64.tar.gz), confirming the filter works correctly.

The Copilot comment is not a legitimate issue. Here's why:

The reviewer is applying old-API logic to the new API. In the old API (/zulu/download/community/v1.0/bundles/), you needed two separate parameters to get JavaFX bundles:

javafx=true

features=fx

In the new Metadata API (/metadata/v1/zulu/packages/), javafx_bundled is a dedicated, purpose-built boolean field that directly filters for JavaFX-bundled packages — it's not an alias for javafx; it's an entirely different parameter on a different API. The live API confirms: passing javafx_bundled=true returns only packages whose names contain -fx-.

There's no features parameter on the new Metadata API at all — it's not just that we dropped it, it doesn't exist in the new API. Adding features=fx to the new URL would likely be ignored or cause an error.

The tests were correctly updated to match the new API's behavior, not to hide a regression.

jameswald · 2026-05-29T01:04:31Z

+      `availability_types=ca`,
+      `page=1`,
+      `page_size=1000`
+    ].join('&');


Implemented with d9458f0.

src/distributions/zulu/installer.ts

Replaced the single page=1&page_size=1000 request with an infinite loop starting at page=1

Each iteration requests page_size=100 entries; the loop breaks when the API returns an empty array

Matches the pattern already used by the Adopt distribution, adapted for Azul's 1-based page indexing

Three test files (zulu-installer.test.ts, zulu-windows-installer.test.ts, zulu-linux-installer.test.ts)

Changed the beforeEach default mock to return [] so URL verification tests terminate the loop after one call

Updated load available versions in each file to use mockReturnValueOnce(data) followed by mockReturnValueOnce([]) to simulate a single full page then end-of-pagination

Updated all URL string expectations from page_size=1000 to page_size=100

jameswald · 2026-05-29T01:06:33Z

+  },
+  {
+    "package_uuid": "test-uuid-12446",
    "name": "zulu17.48.15-ca-jdk17.0.10-win_aarhc4.zip",


zulu17.48.15-ca-jdk17.0.10-win_aarch64.zip is the correct file name according to https://cdn.azul.com/zulu/bin.

Fixed with 0731a04.

jameswald · 2026-05-29T01:17:54Z

 **NOTE:** AdoptOpenJDK got moved to Eclipse Temurin and won't be updated anymore. It is highly recommended to migrate workflows from `adopt` and `adopt-openj9`, to `temurin` and `semeru` respectively, to keep receiving software and security updates. See more details in the [Good-bye AdoptOpenJDK post](https://blog.adoptopenjdk.net/2021/08/goodbye-adoptopenjdk-hello-adoptium/).

-**NOTE:** For Azul Zulu OpenJDK architectures x64 and arm64 are mapped to x86 / arm with proper hw_bitness.
+**NOTE:** For Azul Zulu OpenJDK, architecture `arm64` is mapped to `aarch64` when querying the Azul Metadata API.


I'm definitely not an expert on this but I suspect the x64 mapping is an appropriate change and won't need to be called out in README.md.

Use Azul metadata API

bf97b83

jameswald mentioned this pull request May 29, 2026

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

Open

Document arm64 -> aarch64 mapping in README.md

f1b4065

jameswald marked this pull request as ready for review May 29, 2026 00:46

jameswald requested a review from a team as a code owner May 29, 2026 00:46

Copilot AI review requested due to automatic review settings May 29, 2026 00:46

Copilot AI reviewed May 29, 2026

View reviewed changes

jameswald added 2 commits May 28, 2026 21:03

Paginate through all available versions

d9458f0

Fix typo: win_aarhc4

0731a04

jameswald changed the title ~~Use Azul metadata API~~ Migrate from Zulu Discovery API to Azul Metadata API May 29, 2026

Only query for linux_glibc packages

874ffb6

jameswald force-pushed the azul-metadata-api branch from df4cd23 to 874ffb6 Compare May 29, 2026 11:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate from Zulu Discovery API to Azul Metadata API#1010

Migrate from Zulu Discovery API to Azul Metadata API#1010
jameswald wants to merge 5 commits into
actions:mainfrom
jameswald:azul-metadata-api

jameswald commented May 29, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

jameswald May 29, 2026 •

edited

Loading

Uh oh!

jameswald May 29, 2026

Uh oh!

jameswald May 29, 2026 •

edited

Loading

Uh oh!

jameswald May 29, 2026

Uh oh!

jameswald May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jameswald commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Background

Changes

src/distributions/zulu/models.ts

src/distributions/zulu/installer.ts

README.md

Test fixtures and tests

Related issue

Check list

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

jameswald May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jameswald May 29, 2026

Choose a reason for hiding this comment

Uh oh!

jameswald May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jameswald May 29, 2026

Choose a reason for hiding this comment

Uh oh!

jameswald May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jameswald commented May 29, 2026 •

edited

Loading

`src/distributions/zulu/models.ts`

`src/distributions/zulu/installer.ts`

`README.md`

jameswald May 29, 2026 •

edited

Loading

jameswald May 29, 2026 •

edited

Loading