fix: Maven Toolchains grows unexpectedly

On self-hosted runners toolchains.xml may survive multiple runs and unexpectedly
grow as a result of the toolchains setup simply appending the JDK definition
even if one with the same `type` and `provides.id` already exists.

Restructuring the parsing step and filtering the potentially existing list of
toolchain definitions prevents this and also fixes toolchain.xml files that
already contain duplicates.

Fixes #530

.github/dependabot.yml

@@ -0,0 +1,22 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  # Enable version updates for npm
+  - package-ecosystem: 'npm'
+    # Look for `package.json` and `lock` files in the `root` directory
+    directory: '/'
+    # Check the npm registry for updates every day (weekdays)
+    schedule:
+      interval: 'weekly'
+
+  # Enable version updates for GitHub Actions
+  - package-ecosystem: 'github-actions'
+    # Workflow files stored in the default location of `.github/workflows`
+    # You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.
+    directory: '/'
+    schedule:
+      interval: 'weekly'

.github/workflows/e2e-cache.yml

@@ -121,7 +121,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [macos-13, windows-latest, ubuntu-latest]
+        os: [macos-13, windows-latest, ubuntu-22.04]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -170,7 +170,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [macos-13, windows-latest, ubuntu-latest]
+        os: [macos-13, windows-latest, ubuntu-22.04]
     needs: sbt-save
     steps:
       - name: Checkout

.github/workflows/e2e-versions.yml

@@ -31,7 +31,8 @@ jobs:
             'semeru',
             'corretto',
             'dragonwell',
-            'sapmachine'
+            'sapmachine',
+            'jetbrains'
           ] # internally 'adopt-hotspot' is the same as 'adopt'
         version: ['21', '11', '17']
         exclude:
@@ -70,6 +71,8 @@ jobs:
         with:
           java-version: ${{ matrix.version }}
           distribution: ${{ matrix.distribution }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Verify Java
         run: bash __tests__/verify-java.sh "${{ matrix.version }}" "${{ steps.setup-java.outputs.path }}"
         shell: bash
@@ -103,6 +106,12 @@ jobs:
           - distribution: sapmachine
             os: ubuntu-latest
             version: '17.0.7'
+          - distribution: jetbrains
+            os: ubuntu-latest
+            version: '11.0.11'
+          - distribution: jetbrains
+            os: ubuntu-latest
+            version: '17.0.7'
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -115,6 +124,8 @@ jobs:
       - name: Verify Java
         run: bash __tests__/verify-java.sh "${{ matrix.version }}" "${{ steps.setup-java.outputs.path }}"
         shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   setup-java-check-latest:
     name: ${{ matrix.distribution }} ${{ matrix.version }} - check-latest flag - ${{ matrix.os }}
@@ -125,7 +136,14 @@ jobs:
       matrix:
         os: [macos-latest, windows-latest, ubuntu-latest]
         distribution:
-          ['temurin', 'zulu', 'liberica', 'dragonwell', 'sapmachine']
+          [
+            'temurin',
+            'zulu',
+            'liberica',
+            'dragonwell',
+            'sapmachine',
+            'jetbrains'
+          ]
         exclude:
           - distribution: dragonwell
             os: macos-latest
@@ -139,6 +157,8 @@ jobs:
           distribution: ${{ matrix.distribution }}
           java-version: 11
           check-latest: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Verify Java
         run: bash __tests__/verify-java.sh "11" "${{ steps.setup-java.outputs.path }}"
         shell: bash
@@ -152,7 +172,14 @@ jobs:
       matrix:
         os: [macos-latest, windows-latest, ubuntu-latest]
         distribution:
-          ['temurin', 'zulu', 'liberica', 'dragonwell', 'sapmachine']
+          [
+            'temurin',
+            'zulu',
+            'liberica',
+            'dragonwell',
+            'sapmachine',
+            'jetbrains'
+          ]
         exclude:
           - distribution: dragonwell
             os: macos-latest
@@ -167,6 +194,8 @@ jobs:
           java-version: |
             11
             17
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Verify Java env variables
         run: |
           $versionsArr = "11","17"
@@ -258,7 +287,8 @@ jobs:
       fail-fast: false
       matrix:
         os: [macos-13, windows-latest, ubuntu-latest]
-        distribution: ['temurin', 'zulu', 'liberica', 'semeru', 'sapmachine']
+        distribution:
+          ['temurin', 'zulu', 'liberica', 'semeru', 'sapmachine', 'jetbrains']
         java-package: ['jre']
         version: ['17.0']
         include:
@@ -282,6 +312,47 @@ jobs:
             java-package: jre
             version: '8'
             os: windows-latest
+          - distribution: 'jetbrains'
+            java-package: jdk+jcef
+            version: '11'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jdk+jcef
+            version: '17'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jdk+jcef
+            version: '21'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jre+jcef
+            version: '11'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jre+jcef
+            version: '17'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jre+jcef
+            version: '21'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jdk+ft
+            version: '17'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jdk+ft
+            version: '21'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jre+ft
+            version: '17'
+            os: ubuntu-latest
+          - distribution: 'jetbrains'
+            java-package: jre+ft
+            version: '21'
+            os: ubuntu-latest
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -292,6 +363,8 @@ jobs:
           java-version: ${{ matrix.version }}
           java-package: ${{ matrix.java-package }}
           distribution: ${{ matrix.distribution }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Verify Java
         run: bash __tests__/verify-java.sh "${{ matrix.version }}" "${{ steps.setup-java.outputs.path }}"
         shell: bash
@@ -305,7 +378,7 @@ jobs:
       fail-fast: false
       matrix:
         # x86 is not supported on macOS
-        os: [windows-latest, ubuntu-latest]
+        os: [windows-latest, ubuntu-22.04]
         distribution: ['liberica', 'zulu', 'corretto']
         version: ['11']
     steps:

.github/workflows/publish-immutable-actions.yml

@@ -2,7 +2,8 @@ name: 'Publish Immutable Action Version'
 
 on:
   release:
-    types: [published]
+    types: [released]
+  workflow_dispatch:
 
 jobs:
   publish:
@@ -17,4 +18,4 @@ jobs:
         uses: actions/checkout@v4
       - name: Publish
         id: publish
-        uses: actions/publish-immutable-action@0.0.3
+        uses: actions/publish-immutable-action@v0.0.4

README.md

@@ -110,6 +110,7 @@ Currently, the following distributions are supported:
 | `dragonwell` | Alibaba Dragonwell JDK | [Link](https://dragonwell-jdk.io/) | [Link](https://www.aliyun.com/product/dragonwell/)
 | `sapmachine` | SAP SapMachine JDK/JRE | [Link](https://sapmachine.io/) | [Link](https://github.com/SAP/SapMachine/blob/sapmachine/LICENSE)
 | `graalvm` | Oracle GraalVM | [Link](https://www.graalvm.org/) | [Link](https://www.oracle.com/downloads/licenses/graal-free-license.html)
+| `jetbrains` | JetBrains Runtime | [Link](https://github.com/JetBrains/JetBrainsRuntime/) | [Link](https://github.com/JetBrains/JetBrainsRuntime/blob/main/LICENSE)
 
 **NOTE:** The different distributors can provide discrepant list of available versions / supported configurations. Please refer to the official documentation to see the list of supported versions.
 
@@ -117,6 +118,8 @@ Currently, the following distributions are supported:
 
 **NOTE:** For Azul Zulu OpenJDK architectures x64 and arm64 are mapped to x86 / arm with proper hw_bitness.
 
+**NOTE:** To comply with the GraalVM Free Terms and Conditions (GFTC) license, it is recommended to use GraalVM JDK 17 version 17.0.12, as this is the only version of GraalVM JDK 17 available under the GFTC license. Additionally, it is encouraged to consider upgrading to GraalVM JDK 21, which offers the latest features and improvements.
+
 ### Caching packages dependencies
 The action has a built-in functionality for caching and restoring dependencies. It uses [toolkit/cache](https://github.com/actions/toolkit/tree/main/packages/cache) under hood for caching dependencies but requires less configuration settings. Supported package managers are gradle, maven and sbt. The format of the used cache key is `setup-java-${{ platform }}-${{ packageManager }}-${{ fileHash }}`, where the hash is based on the following files:
 
@@ -272,6 +275,15 @@ In the example above multiple JDKs are installed for the same job. The result af
 - [Modifying Maven Toolchains](docs/advanced-usage.md#Modifying-Maven-Toolchains)
 - [Java Version File](docs/advanced-usage.md#Java-version-file)
 
+## Recommended permissions
+
+When using the `setup-java` action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:
+
+```yaml
+permissions:
+  contents: read # access to check out code and install dependencies
+```
+
 ## License
 
 The scripts and documentation in this project are released under the [MIT License](LICENSE).

__tests__/distributors/jetbrains-installer.test.ts

@@ -0,0 +1,118 @@
+import https from 'https';
+import {HttpClient} from '@actions/http-client';
+import {JetBrainsDistribution} from '../../src/distributions/jetbrains/installer';
+
+import manifestData from '../data/jetbrains.json';
+import os from 'os';
+
+describe('getAvailableVersions', () => {
+  let spyHttpClient: jest.SpyInstance;
+
+  beforeEach(() => {
+    spyHttpClient = jest.spyOn(HttpClient.prototype, 'getJson');
+    spyHttpClient.mockReturnValue({
+      statusCode: 200,
+      headers: {},
+      result: []
+    });
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+    jest.clearAllMocks();
+    jest.restoreAllMocks();
+  });
+
+  it('load available versions', async () => {
+    spyHttpClient = jest.spyOn(HttpClient.prototype, 'getJson');
+    spyHttpClient.mockReturnValueOnce({
+      statusCode: 200,
+      headers: {},
+      result: manifestData as any
+    });
+
+    const distribution = new JetBrainsDistribution({
+      version: '17',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    const availableVersions = await distribution['getAvailableVersions']();
+    expect(availableVersions).not.toBeNull();
+
+    const length =
+      os.platform() === 'win32' ? manifestData.length : manifestData.length + 2;
+    expect(availableVersions.length).toBe(length);
+  }, 10_000);
+});
+
+describe('findPackageForDownload', () => {
+  it.each([
+    ['17', '17.0.11+1207.24'],
+    ['11.0', '11.0.16+2043.64'],
+    ['11.0.11', '11.0.11+1542.1'],
+    ['21.0.2', '21.0.2+375.1'],
+    ['21', '21.0.3+465.3'],
+    ['x', '21.0.3+465.3']
+  ])('version is resolved correctly %s -> %s', async (input, expected) => {
+    const distribution = new JetBrainsDistribution({
+      version: input,
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => manifestData as any;
+    const resolvedVersion = await distribution['findPackageForDownload'](input);
+    expect(resolvedVersion.version).toBe(expected);
+  });
+
+  it.each(['17', '11.0', '11.0.11', '21.0.2', '21'])(
+    'version %s can be downloaded',
+    async input => {
+      const distribution = new JetBrainsDistribution({
+        version: input,
+        architecture: 'x64',
+        packageType: 'jdk',
+        checkLatest: false
+      });
+      distribution['getAvailableVersions'] = async () => manifestData as any;
+      const resolvedVersion = await distribution['findPackageForDownload'](
+        input
+      );
+      const url = resolvedVersion.url;
+      const options = {method: 'HEAD'};
+
+      https.request(url, options, res => {
+        // JetBrains uses 403 for inexistent packages
+        expect(res.statusCode).not.toBe(403);
+        res.resume();
+      });
+    }
+  );
+
+  it('version is not found', async () => {
+    const distribution = new JetBrainsDistribution({
+      version: '8.0.452',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => manifestData as any;
+    await expect(distribution['findPackageForDownload']('8.x')).rejects.toThrow(
+      /Could not find satisfied version for SemVer */
+    );
+  });
+
+  it('version list is empty', async () => {
+    const distribution = new JetBrainsDistribution({
+      version: '8',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => [];
+    await expect(distribution['findPackageForDownload']('8')).rejects.toThrow(
+      /Could not find satisfied version for SemVer */
+    );
+  });
+});

__tests__/toolchains.test.ts

@@ -143,7 +143,20 @@ describe('toolchains tests', () => {
         </toolchain>
       </toolchains>`;
     const result = `<?xml version="1.0"?>
-<toolchains>
+<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>17</version>
+      <vendor>Eclipse Temurin</vendor>
+      <id>temurin_17</id>
+    </provides>
+    <configuration>
+      <jdkHome>/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64</jdkHome>
+    </configuration>
+  </toolchain>
   <toolchain>
     <type>jdk</type>
     <provides>
@@ -155,6 +168,442 @@ describe('toolchains tests', () => {
       <jdkHome>/opt/jdk/sun/1.6</jdkHome>
     </configuration>
   </toolchain>
+</toolchains>`;
+
+    fs.mkdirSync(m2Dir, {recursive: true});
+    fs.writeFileSync(toolchainsFile, originalFile);
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+
+    await toolchains.createToolchainsSettings({
+      jdkInfo,
+      settingsDirectory: m2Dir,
+      overwriteSettings: true
+    });
+
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+    expect(fs.readFileSync(toolchainsFile, 'utf-8')).toEqual(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    );
+    expect(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    ).toEqual(result);
+  }, 100000);
+
+  it('does not discard custom elements in existing toolchain definitions', async () => {
+    const jdkInfo = {
+      version: '17',
+      vendor: 'Eclipse Temurin',
+      id: 'temurin_17',
+      jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64'
+    };
+
+    const originalFile = `<toolchains>
+        <toolchain>
+          <type>jdk</type>
+          <provides>
+            <version>1.6</version>
+            <vendor>Sun</vendor>
+            <id>sun_1.6</id>
+            <custom>foo</custom>
+          </provides>
+          <configuration>
+            <jdkHome>/opt/jdk/sun/1.6</jdkHome>
+            <fooHome>/usr/local/bin/bash</fooHome>
+          </configuration>
+        </toolchain>
+      </toolchains>`;
+    const result = `<?xml version="1.0"?>
+<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>17</version>
+      <vendor>Eclipse Temurin</vendor>
+      <id>temurin_17</id>
+    </provides>
+    <configuration>
+      <jdkHome>/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64</jdkHome>
+    </configuration>
+  </toolchain>
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>1.6</version>
+      <vendor>Sun</vendor>
+      <id>sun_1.6</id>
+      <custom>foo</custom>
+    </provides>
+    <configuration>
+      <jdkHome>/opt/jdk/sun/1.6</jdkHome>
+      <fooHome>/usr/local/bin/bash</fooHome>
+    </configuration>
+  </toolchain>
+</toolchains>`;
+
+    fs.mkdirSync(m2Dir, {recursive: true});
+    fs.writeFileSync(toolchainsFile, originalFile);
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+
+    await toolchains.createToolchainsSettings({
+      jdkInfo,
+      settingsDirectory: m2Dir,
+      overwriteSettings: true
+    });
+
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+    expect(fs.readFileSync(toolchainsFile, 'utf-8')).toEqual(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    );
+    expect(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    ).toEqual(result);
+  }, 100000);
+
+  it('does not discard existing, custom toolchain definitions', async () => {
+    const jdkInfo = {
+      version: '17',
+      vendor: 'Eclipse Temurin',
+      id: 'temurin_17',
+      jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64'
+    };
+
+    const originalFile = `<toolchains>
+        <toolchain>
+            <type>foo</type>
+            <provides>
+                <custom>baz</custom>
+            </provides>
+            <configuration>
+                <fooHome>/usr/local/bin/foo</fooHome>
+            </configuration>
+        </toolchain>
+      </toolchains>`;
+    const result = `<?xml version="1.0"?>
+<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>17</version>
+      <vendor>Eclipse Temurin</vendor>
+      <id>temurin_17</id>
+    </provides>
+    <configuration>
+      <jdkHome>/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64</jdkHome>
+    </configuration>
+  </toolchain>
+  <toolchain>
+    <type>foo</type>
+    <provides>
+      <custom>baz</custom>
+    </provides>
+    <configuration>
+      <fooHome>/usr/local/bin/foo</fooHome>
+    </configuration>
+  </toolchain>
+</toolchains>`;
+
+    fs.mkdirSync(m2Dir, {recursive: true});
+    fs.writeFileSync(toolchainsFile, originalFile);
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+
+    await toolchains.createToolchainsSettings({
+      jdkInfo,
+      settingsDirectory: m2Dir,
+      overwriteSettings: true
+    });
+
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+    expect(fs.readFileSync(toolchainsFile, 'utf-8')).toEqual(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    );
+    expect(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    ).toEqual(result);
+  }, 100000);
+
+  it('does not duplicate existing toolchain definitions', async () => {
+    const jdkInfo = {
+      version: '17',
+      vendor: 'Eclipse Temurin',
+      id: 'temurin_17',
+      jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64'
+    };
+
+    const originalFile = `<toolchains>
+      <toolchain>
+        <type>jdk</type>
+        <provides>
+          <version>17</version>
+          <vendor>Eclipse Temurin</vendor>
+          <id>temurin_17</id>
+        </provides>
+        <configuration>
+          <jdkHome>/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64</jdkHome>
+        </configuration>
+      </toolchain>
+      </toolchains>`;
+    const result = `<?xml version="1.0"?>
+<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>17</version>
+      <vendor>Eclipse Temurin</vendor>
+      <id>temurin_17</id>
+    </provides>
+    <configuration>
+      <jdkHome>/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64</jdkHome>
+    </configuration>
+  </toolchain>
+</toolchains>`;
+
+    fs.mkdirSync(m2Dir, {recursive: true});
+    fs.writeFileSync(toolchainsFile, originalFile);
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+
+    await toolchains.createToolchainsSettings({
+      jdkInfo,
+      settingsDirectory: m2Dir,
+      overwriteSettings: true
+    });
+
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+    expect(fs.readFileSync(toolchainsFile, 'utf-8')).toEqual(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    );
+    expect(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    ).toEqual(result);
+  }, 100000);
+
+  it('does not duplicate existing toolchain definitions if multiple exist', async () => {
+    const jdkInfo = {
+      version: '17',
+      vendor: 'Eclipse Temurin',
+      id: 'temurin_17',
+      jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64'
+    };
+
+    const originalFile = `<toolchains>
+        <toolchain>
+          <type>jdk</type>
+          <provides>
+            <version>1.6</version>
+            <vendor>Sun</vendor>
+            <id>sun_1.6</id>
+          </provides>
+          <configuration>
+            <jdkHome>/opt/jdk/sun/1.6</jdkHome>
+          </configuration>
+        </toolchain>
+      <toolchain>
+        <type>jdk</type>
+        <provides>
+          <version>17</version>
+          <vendor>Eclipse Temurin</vendor>
+          <id>temurin_17</id>
+        </provides>
+        <configuration>
+          <jdkHome>/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64</jdkHome>
+        </configuration>
+      </toolchain>
+      </toolchains>`;
+    const result = `<?xml version="1.0"?>
+<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>17</version>
+      <vendor>Eclipse Temurin</vendor>
+      <id>temurin_17</id>
+    </provides>
+    <configuration>
+      <jdkHome>/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64</jdkHome>
+    </configuration>
+  </toolchain>
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>1.6</version>
+      <vendor>Sun</vendor>
+      <id>sun_1.6</id>
+    </provides>
+    <configuration>
+      <jdkHome>/opt/jdk/sun/1.6</jdkHome>
+    </configuration>
+  </toolchain>
+</toolchains>`;
+
+    fs.mkdirSync(m2Dir, {recursive: true});
+    fs.writeFileSync(toolchainsFile, originalFile);
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+
+    await toolchains.createToolchainsSettings({
+      jdkInfo,
+      settingsDirectory: m2Dir,
+      overwriteSettings: true
+    });
+
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+    expect(fs.readFileSync(toolchainsFile, 'utf-8')).toEqual(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    );
+    expect(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    ).toEqual(result);
+  }, 100000);
+
+  it('handles an empty list of existing toolchains correctly', async () => {
+    const jdkInfo = {
+      version: '17',
+      vendor: 'Eclipse Temurin',
+      id: 'temurin_17',
+      jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64'
+    };
+
+    const originalFile = `<toolchains>
+      </toolchains>`;
+    const result = `<?xml version="1.0"?>
+<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>17</version>
+      <vendor>Eclipse Temurin</vendor>
+      <id>temurin_17</id>
+    </provides>
+    <configuration>
+      <jdkHome>/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64</jdkHome>
+    </configuration>
+  </toolchain>
+</toolchains>`;
+
+    fs.mkdirSync(m2Dir, {recursive: true});
+    fs.writeFileSync(toolchainsFile, originalFile);
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+
+    await toolchains.createToolchainsSettings({
+      jdkInfo,
+      settingsDirectory: m2Dir,
+      overwriteSettings: true
+    });
+
+    expect(fs.existsSync(m2Dir)).toBe(true);
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+    expect(fs.readFileSync(toolchainsFile, 'utf-8')).toEqual(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    );
+    expect(
+      toolchains.generateToolchainDefinition(
+        originalFile,
+        jdkInfo.version,
+        jdkInfo.vendor,
+        jdkInfo.id,
+        jdkInfo.jdkHome
+      )
+    ).toEqual(result);
+  }, 100000);
+
+  it('handles an empty existing toolchains.xml correctly', async () => {
+    const jdkInfo = {
+      version: '17',
+      vendor: 'Eclipse Temurin',
+      id: 'temurin_17',
+      jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64'
+    };
+
+    const originalFile = ``;
+    const result = `<?xml version="1.0"?>
+<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
   <toolchain>
     <type>jdk</type>
     <provides>

docs/advanced-usage.md

@@ -10,6 +10,7 @@
   - [Alibaba Dragonwell](#Alibaba-Dragonwell)
   - [SapMachine](#SapMachine)
   - [GraalVM](#GraalVM)
+  - [JetBrains](#JetBrains)
 - [Installing custom Java package type](#Installing-custom-Java-package-type)
 - [Installing custom Java architecture](#Installing-custom-Java-architecture)
 - [Installing custom Java distribution from local file](#Installing-Java-from-local-file)
@@ -171,6 +172,50 @@ steps:
     native-image -cp java HelloWorldApp
 ```
 
+### JetBrains
+
+**NOTE:** JetBrains is only available for LTS versions on 11 or later (11, 17, 21, etc.).
+
+Not all minor LTS versions are guarenteed to be available, since JetBrains considers what to ship IntelliJ IDEA with, most commonly on JDK 11.
+For example, `11.0.24` is not available but `11.0.16` is.
+
+```yaml
+steps:
+- uses: actions/checkout@v4
+- uses: actions/setup-java@v4
+  with:
+    distribution: 'jetbrains'
+    java-version: '11'
+- run: java -cp java HelloWorldApp
+```
+
+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
+GitHub token to the action to increase the rate limit. Set the `GITHUB_TOKEN` environment variable to the value of your GitHub token in the workflow file.
+
+```yaml
+steps:
+- uses: actions/checkout@v4
+- uses: actions/setup-java@v4
+  with:
+    distribution: 'jetbrains'
+    java-version: '17'
+    java-package: 'jdk' # optional (jdk, jre, jdk+jcef, jre+jcef, jdk+ft, or jre+ft) - defaults to jdk
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+- run: java -cp java HelloWorldApp
+```
+
+You can specify your package type (as shown in the [releases page](https://github.com/JetBrains/JetBrainsRuntime/releases/)) in the `java-package` parameter. 
+The available package types are:
+
+- `jdk` - JBRSDK
+- `jre` - JBR (Vanilla)
+- `jdk+jcef` - JBRSDK with JCEF
+- `jre+jcef` - JBR with JCEF
+- `jdk+ft` - JBRSDK (FreeType)
+- `jre+ft` - JBR (FreeType)
+
+
 ## Installing custom Java package type
 ```yaml
 steps:
@@ -183,7 +228,6 @@ steps:
 - run: java -cp java HelloWorldApp
 ```
 
-
 ## Installing custom Java architecture
 
 ```yaml

package.json

@@ -26,31 +26,31 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@actions/cache": "^3.2.4",
+    "@actions/cache": "^4.0.3",
     "@actions/core": "^1.10.0",
     "@actions/exec": "^1.0.4",
-    "@actions/glob": "^0.4.0",
-    "@actions/http-client": "^2.2.1",
+    "@actions/glob": "^0.5.0",
+    "@actions/http-client": "^2.2.3",
     "@actions/io": "^1.0.2",
     "@actions/tool-cache": "^2.0.1",
     "semver": "^7.6.0",
     "xmlbuilder2": "^2.4.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.12",
+    "@types/jest": "^29.5.14",
     "@types/node": "^20.11.24",
     "@types/semver": "^7.5.8",
-    "@typescript-eslint/eslint-plugin": "^5.54.0",
-    "@typescript-eslint/parser": "^5.54.0",
+    "@typescript-eslint/eslint-plugin": "^8.35.1",
+    "@typescript-eslint/parser": "^8.35.1",
     "@vercel/ncc": "^0.38.1",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^8.6.0",
-    "eslint-plugin-jest": "^27.9.0",
+    "eslint-plugin-jest": "^29.0.1",
     "eslint-plugin-node": "^11.1.0",
     "jest": "^29.7.0",
     "jest-circus": "^29.7.0",
     "prettier": "^2.8.4",
-    "ts-jest": "^29.1.2",
+    "ts-jest": "^29.3.0",
     "typescript": "^5.3.3"
   },
   "bugs": {

src/distributions/base-installer.ts

@@ -51,14 +51,36 @@ export abstract class JavaBase {
       core.info(`Resolved Java ${foundJava.version} from tool-cache`);
     } else {
       core.info('Trying to resolve the latest version from remote');
-      const javaRelease = await this.findPackageForDownload(this.version);
-      core.info(`Resolved latest version as ${javaRelease.version}`);
-      if (foundJava?.version === javaRelease.version) {
-        core.info(`Resolved Java ${foundJava.version} from tool-cache`);
-      } else {
-        core.info('Trying to download...');
-        foundJava = await this.downloadTool(javaRelease);
-        core.info(`Java ${foundJava.version} was downloaded`);
+      try {
+        const javaRelease = await this.findPackageForDownload(this.version);
+        core.info(`Resolved latest version as ${javaRelease.version}`);
+        if (foundJava?.version === javaRelease.version) {
+          core.info(`Resolved Java ${foundJava.version} from tool-cache`);
+        } else {
+          core.info('Trying to download...');
+          foundJava = await this.downloadTool(javaRelease);
+          core.info(`Java ${foundJava.version} was downloaded`);
+        }
+      } catch (error: any) {
+        if (error instanceof tc.HTTPError) {
+          if (error.httpStatusCode === 403) {
+            core.error('HTTP 403: Permission denied or access restricted.');
+          } else if (error.httpStatusCode === 429) {
+            core.warning('HTTP 429: Rate limit exceeded. Please retry later.');
+          } else {
+            core.error(`HTTP ${error.httpStatusCode}: ${error.message}`);
+          }
+        } else {
+          const message =
+            error instanceof Error ? error.message : JSON.stringify(error);
+          core.error(
+            `Java setup failed due to network issue or timeout: ${message}`
+          );
+        }
+        if (error instanceof Error && error.stack) {
+          core.debug(error.stack);
+        }
+        throw error;
       }
     }
 

src/distributions/distribution-factory.ts

@@ -12,6 +12,7 @@ import {OracleDistribution} from './oracle/installer';
 import {DragonwellDistribution} from './dragonwell/installer';
 import {SapMachineDistribution} from './sapmachine/installer';
 import {GraalVMDistribution} from './graalvm/installer';
+import {JetBrainsDistribution} from './jetbrains/installer';
 
 enum JavaDistribution {
   Adopt = 'adopt',
@@ -27,7 +28,8 @@ enum JavaDistribution {
   Oracle = 'oracle',
   Dragonwell = 'dragonwell',
   SapMachine = 'sapmachine',
-  GraalVM = 'graalvm'
+  GraalVM = 'graalvm',
+  JetBrains = 'jetbrains'
 }
 
 export function getJavaDistribution(
@@ -72,6 +74,8 @@ export function getJavaDistribution(
       return new SapMachineDistribution(installerOptions);
     case JavaDistribution.GraalVM:
       return new GraalVMDistribution(installerOptions);
+    case JavaDistribution.JetBrains:
+      return new JetBrainsDistribution(installerOptions);
     default:
       return null;
   }

src/distributions/jetbrains/installer.ts

@@ -0,0 +1,246 @@
+import * as core from '@actions/core';
+import * as tc from '@actions/tool-cache';
+
+import fs from 'fs';
+import path from 'path';
+import semver from 'semver';
+
+import {JavaBase} from '../base-installer';
+import {IJetBrainsRawVersion, IJetBrainsVersion} from './models';
+import {
+  JavaDownloadRelease,
+  JavaInstallerOptions,
+  JavaInstallerResults
+} from '../base-models';
+import {extractJdkFile, isVersionSatisfies} from '../../util';
+import {OutgoingHttpHeaders} from 'http';
+import {HttpCodes} from '@actions/http-client';
+
+export class JetBrainsDistribution extends JavaBase {
+  constructor(installerOptions: JavaInstallerOptions) {
+    super('JetBrains', installerOptions);
+  }
+
+  protected async findPackageForDownload(
+    range: string
+  ): Promise<JavaDownloadRelease> {
+    const versionsRaw = await this.getAvailableVersions();
+
+    const versions = versionsRaw.map(v => {
+      const formattedVersion = `${v.semver}+${v.build}`;
+
+      return {
+        version: formattedVersion,
+        url: v.url
+      } as JavaDownloadRelease;
+    });
+
+    const satisfiedVersions = versions
+      .filter(item => isVersionSatisfies(range, item.version))
+      .sort((a, b) => {
+        return -semver.compareBuild(a.version, b.version);
+      });
+
+    const resolvedFullVersion =
+      satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
+    if (!resolvedFullVersion) {
+      const availableOptions = versionsRaw
+        .map(item => `${item.tag_name} (${item.semver}+${item.build})`)
+        .join(', ');
+      const availableOptionsMessage = availableOptions
+        ? `\nAvailable versions: ${availableOptions}`
+        : '';
+      throw new Error(
+        `Could not find satisfied version for SemVer '${range}'. ${availableOptionsMessage}`
+      );
+    }
+
+    return resolvedFullVersion;
+  }
+
+  protected async downloadTool(
+    javaRelease: JavaDownloadRelease
+  ): Promise<JavaInstallerResults> {
+    core.info(
+      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
+    );
+
+    const javaArchivePath = await tc.downloadTool(javaRelease.url);
+
+    core.info(`Extracting Java archive...`);
+    const extractedJavaPath = await extractJdkFile(javaArchivePath, 'tar.gz');
+
+    const archiveName = fs.readdirSync(extractedJavaPath)[0];
+    const archivePath = path.join(extractedJavaPath, archiveName);
+    const version = this.getToolcacheVersionName(javaRelease.version);
+
+    const javaPath = await tc.cacheDir(
+      archivePath,
+      this.toolcacheFolderName,
+      version,
+      this.architecture
+    );
+
+    return {version: javaRelease.version, path: javaPath};
+  }
+
+  private async getAvailableVersions(): Promise<IJetBrainsVersion[]> {
+    const platform = this.getPlatformOption();
+    const arch = this.distributionArchitecture();
+
+    if (core.isDebug()) {
+      console.time('Retrieving available versions for JBR took'); // eslint-disable-line no-console
+    }
+
+    // need to iterate through all pages to retrieve the list of all versions
+    // GitHub API doesn't provide way to retrieve the count of pages to iterate so infinity loop
+    let page_index = 1;
+    const rawVersions: IJetBrainsRawVersion[] = [];
+    const bearerToken = process.env.GITHUB_TOKEN;
+
+    while (true) {
+      const requestArguments = `per_page=100&page=${page_index}`;
+      const requestHeaders: OutgoingHttpHeaders = {};
+
+      if (bearerToken) {
+        requestHeaders['Authorization'] = `Bearer ${bearerToken}`;
+      }
+
+      const rawUrl = `https://api.github.com/repos/JetBrains/JetBrainsRuntime/releases?${requestArguments}`;
+
+      if (core.isDebug() && page_index === 1) {
+        // url is identical except page_index so print it once for debug
+        core.debug(`Gathering available versions from '${rawUrl}'`);
+      }
+
+      const paginationPageResult = (
+        await this.http.getJson<IJetBrainsRawVersion[]>(rawUrl, requestHeaders)
+      ).result;
+      if (!paginationPageResult || paginationPageResult.length === 0) {
+        // break infinity loop because we have reached end of pagination
+        break;
+      }
+
+      const paginationPage: IJetBrainsRawVersion[] =
+        paginationPageResult.filter(version =>
+          this.stable ? !version.prerelease : version.prerelease
+        );
+      if (!paginationPage || paginationPage.length === 0) {
+        // break infinity loop because we have reached end of pagination
+        break;
+      }
+
+      rawVersions.push(...paginationPage);
+      page_index++;
+    }
+
+    if (this.stable) {
+      // Add versions not available from the API but are downloadable
+      const hidden = ['11_0_10b1145.115', '11_0_11b1341.60'];
+      rawVersions.push(
+        ...hidden.map(tag => ({tag_name: tag, name: tag, prerelease: false}))
+      );
+    }
+
+    const versions0 = rawVersions.map(async v => {
+      // Release tags look like one of these:
+      // jbr-release-21.0.3b465.3
+      // jbr17-b87.7
+      // jb11_0_11-b87.7
+      // jbr11_0_15b2043.56
+      // 11_0_11b1536.2
+      // 11_0_11-b1522
+      const tag = v.tag_name;
+
+      // Extract version string
+      const vstring = tag
+        .replace('jbr-release-', '')
+        .replace('jbr', '')
+        .replace('jb', '')
+        .replace('-', '');
+
+      const vsplit = vstring.split('b');
+      let semver = vsplit[0];
+      const build = vsplit[1];
+
+      // Normalize semver
+      if (!semver.includes('.') && !semver.includes('_'))
+        semver = `${semver}.0.0`;
+
+      // Construct URL
+      let type: string;
+      switch (this.packageType ?? '') {
+        case 'jre':
+          type = 'jbr';
+          break;
+        case 'jdk+jcef':
+          type = 'jbrsdk_jcef';
+          break;
+        case 'jre+jcef':
+          type = 'jbr_jcef';
+          break;
+        case 'jdk+ft':
+          type = 'jbrsdk_ft';
+          break;
+        case 'jre+ft':
+          type = 'jbr_ft';
+          break;
+        default:
+          type = 'jbrsdk';
+          break;
+      }
+
+      let url = `https://cache-redirector.jetbrains.com/intellij-jbr/${type}-${semver}-${platform}-${arch}-b${build}.tar.gz`;
+      let include = false;
+
+      const res = await this.http.head(url);
+      if (res.message.statusCode === HttpCodes.OK) {
+        include = true;
+      } else {
+        url = `https://cache-redirector.jetbrains.com/intellij-jbr/${type}_nomod-${semver}-${platform}-${arch}-b${build}.tar.gz`;
+        const res2 = await this.http.head(url);
+        if (res2.message.statusCode === HttpCodes.OK) {
+          include = true;
+        }
+      }
+
+      const version = {
+        tag_name: tag,
+        semver: semver.replace(/_/g, '.'),
+        build: build,
+        url: url
+      } as IJetBrainsVersion;
+
+      return {
+        item: version,
+        include: include
+      };
+    });
+
+    const versions = await Promise.all(versions0).then(res =>
+      res.filter(item => item.include).map(item => item.item)
+    );
+
+    if (core.isDebug()) {
+      core.startGroup('Print information about available versions');
+      console.timeEnd('Retrieving available versions for JBR took'); // eslint-disable-line no-console
+      core.debug(`Available versions: [${versions.length}]`);
+      core.debug(versions.map(item => item.semver).join(', '));
+      core.endGroup();
+    }
+
+    return versions;
+  }
+
+  private getPlatformOption(): string {
+    // Jetbrains has own platform names so need to map them
+    switch (process.platform) {
+      case 'darwin':
+        return 'osx';
+      case 'win32':
+        return 'windows';
+      default:
+        return process.platform;
+    }
+  }
+}

src/distributions/jetbrains/models.ts

@@ -0,0 +1,14 @@
+// Raw Model from https://api.github.com/repos/JetBrains/JetBrainsRuntime/releases
+
+export interface IJetBrainsRawVersion {
+  tag_name: string;
+  name: string;
+  prerelease: boolean;
+}
+
+export interface IJetBrainsVersion {
+  tag_name: string;
+  semver: string;
+  build: string;
+  url: string;
+}

src/distributions/microsoft/installer.ts

@@ -116,7 +116,7 @@ export class MicrosoftDistributions extends JavaBase {
       }
     } catch (err) {
       core.debug(
-        `Http request for microsoft-openjdk-versions.json failed with status code: ${response?.statusCode}`
+        `Http request for microsoft-openjdk-versions.json failed with status code: ${response?.statusCode}. Error: ${err}`
       );
       return null;
     }

src/toolchains.ts

@@ -84,47 +84,59 @@ export function generateToolchainDefinition(
   id: string,
   jdkHome: string
 ) {
-  let xmlObj;
-  if (original?.length) {
-    xmlObj = xmlCreate(original)
-      .root()
-      .ele({
-        toolchain: {
-          type: 'jdk',
-          provides: {
-            version: `${version}`,
-            vendor: `${vendor}`,
-            id: `${id}`
-          },
-          configuration: {
-            jdkHome: `${jdkHome}`
-          }
-        }
-      });
-  } else
-    xmlObj = xmlCreate({
-      toolchains: {
-        '@xmlns': 'http://maven.apache.org/TOOLCHAINS/1.1.0',
-        '@xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
-        '@xsi:schemaLocation':
-          'http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd',
-        toolchain: [
-          {
-            type: 'jdk',
-            provides: {
-              version: `${version}`,
-              vendor: `${vendor}`,
-              id: `${id}`
-            },
-            configuration: {
-              jdkHome: `${jdkHome}`
-            }
-          }
-        ]
+  let jsToolchains: Toolchain[] = [
+    {
+      type: 'jdk',
+      provides: {
+        version: `${version}`,
+        vendor: `${vendor}`,
+        id: `${id}`
+      },
+      configuration: {
+        jdkHome: `${jdkHome}`
       }
-    });
+    }
+  ];
+  if (original?.length) {
+    // convert existing toolchains into TS native objects for better handling
+    // xmlbuilder2 will convert the document into a `{toolchains: { toolchain: [] | {} }}` structure
+    // instead of the desired `toolchains: [{}]` one or simply `[{}]`
+    const jsObj = xmlCreate(original)
+      .root()
+      .toObject() as unknown as ExtractedToolchains;
+    if (jsObj.toolchains && jsObj.toolchains.toolchain) {
+      // in case only a single child exists xmlbuilder2 will not create an array and using verbose = true equally doesn't work here
+      // See https://oozcitak.github.io/xmlbuilder2/serialization.html#js-object-and-map-serializers for details
+      if (Array.isArray(jsObj.toolchains.toolchain)) {
+        jsToolchains.push(...jsObj.toolchains.toolchain);
+      } else {
+        jsToolchains.push(jsObj.toolchains.toolchain);
+      }
+    }
 
-  return xmlObj.end({
+    // remove potential duplicates based on type & id (which should be a unique combination);
+    // self.findIndex will only return the first occurrence, ensuring duplicates are skipped
+    jsToolchains = jsToolchains.filter(
+      (value, index, self) =>
+        // ensure non-jdk toolchains are kept in the results, we must not touch them because they belong to the user
+        value.type !== 'jdk' ||
+        index ===
+          self.findIndex(
+            t => t.type === value.type && t.provides.id === value.provides.id
+          )
+    );
+  }
+
+  // TODO: technically bad because we shouldn't re-create the toolchains root node (with possibly different schema values) if it already exists, however, just overriding the toolchain array with xmlbuilder2 is … uh non-trivial
+  return xmlCreate({
+    toolchains: {
+      '@xmlns': 'http://maven.apache.org/TOOLCHAINS/1.1.0',
+      '@xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+      '@xsi:schemaLocation':
+        'http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd',
+      toolchain: jsToolchains
+    }
+  }).end({
     format: 'xml',
     wellFormed: false,
     headless: false,
@@ -167,3 +179,22 @@ async function writeToolchainsFileToDisk(
     flag: 'w'
   });
 }
+
+interface ExtractedToolchains {
+  toolchains: {
+    toolchain: Toolchain[] | Toolchain;
+  };
+}
+
+// Toolchain type definition according to Maven Toolchains XSD 1.1.0
+interface Toolchain {
+  type: string;
+  provides:
+    | {
+        version: string;
+        vendor: string;
+        id: string;
+      }
+    | any;
+  configuration: any;
+}