Backport #1111: Preserve Maven toolchains across repeated setup-java runs (#1099) (#1113)

* Preserve Maven toolchains across repeated setup-java runs (#1099)

Backport of #1111 to releases/v5.

Toolchain generation was gated behind the `overwrite-settings` input,
which is documented to control only regeneration of `settings.xml`.
Because `generateToolchainDefinition` already performs a non-destructive
merge (existing JDK, custom, and user-managed toolchains are preserved,
and only an entry with the same `type` + `provides.id` is replaced),
skipping the write when `overwrite-settings: false` caused later
setup-java executions to drop toolchain entries registered by earlier
runs.

Decouple toolchains generation from `overwrite-settings`: the toolchains
file is now always written, so consecutive runs accumulate every JDK.
`settings.xml` behavior (auth.ts) is unchanged.

- src/toolchains.ts: drop overwriteSettings from configureToolchains /
  createToolchainsSettings / writeToolchainsFileToDisk; always write.
- __tests__/toolchains.test.ts: update call sites, rewrite the
  "does not overwrite" test to assert non-destructive extension, and add
  a regression test for consecutive configureToolchains executions.
- docs/advanced-usage.md: clarify merge is non-destructive and
  independent of overwrite-settings.
- dist/setup/index.js: rebuilt.

Fixes #1099

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

__tests__/toolchains.test.ts

@@ -46,8 +46,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: altHome,
+      settingsDirectory: altHome
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(false);
@@ -95,8 +94,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -177,8 +175,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -263,8 +260,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -341,8 +337,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -412,8 +407,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -505,8 +499,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -565,8 +558,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -624,8 +616,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -708,8 +699,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -788,8 +778,7 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: true
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
@@ -814,7 +803,7 @@ describe('toolchains tests', () => {
     ).toEqual(result);
   }, 100000);
 
-  it('does not overwrite existing toolchains.xml files', async () => {
+  it('extends existing toolchains.xml files instead of overwriting them', async () => {
     const jdkInfo = {
       version: '17',
       vendor: 'Eclipse Temurin',
@@ -843,13 +832,20 @@ describe('toolchains tests', () => {
 
     await toolchains.createToolchainsSettings({
       jdkInfo,
-      settingsDirectory: m2Dir,
+      settingsDirectory: m2Dir
-      overwriteSettings: false
     });
 
     expect(fs.existsSync(m2Dir)).toBe(true);
     expect(fs.existsSync(toolchainsFile)).toBe(true);
-    expect(fs.readFileSync(toolchainsFile, 'utf-8')).toEqual(originalFile);
+
+    const updated = fs.readFileSync(toolchainsFile, 'utf-8');
+    // The pre-existing (Sun 1.6) toolchain must be preserved ...
+    expect(updated).toContain('<id>sun_1.6</id>');
+    expect(updated).toContain('<jdkHome>/opt/jdk/sun/1.6</jdkHome>');
+    // ... and the newly installed JDK must be included in the merged result.
+    expect(updated).toContain('<id>temurin_17</id>');
+    expect(updated).toContain('<vendor>Eclipse Temurin</vendor>');
+    expect(updated).toContain(`<jdkHome>${jdkInfo.jdkHome}</jdkHome>`);
   }, 100000);
 
   it('generates valid toolchains.xml with minimal configuration', () => {
@@ -914,4 +910,55 @@ describe('toolchains tests', () => {
       )
     );
   }, 100000);
+
+  it('preserves toolchains from previous executions across multiple setup-java runs', async () => {
+    // Regression test for https://github.com/actions/setup-java/issues/1099
+    // Running setup-java several times in the same job (e.g. multiple steps / multiple
+    // java-version entries) must accumulate every JDK in toolchains.xml rather
+    // than replacing previously registered entries.
+    jest.spyOn(core, 'getInput').mockImplementation((name: string) => {
+      if (name === 'settings-path') return m2Dir;
+      return '';
+    });
+
+    const runs = [
+      {
+        version: '8',
+        distributionName: 'temurin',
+        id: 'temurin_8',
+        jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/8.0.1-12/x64'
+      },
+      {
+        version: '11',
+        distributionName: 'temurin',
+        id: 'temurin_11',
+        jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/11.0.1-12/x64'
+      },
+      {
+        version: '17',
+        distributionName: 'temurin',
+        id: 'temurin_17',
+        jdkHome: '/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/17.0.1-12/x64'
+      }
+    ];
+
+    for (const run of runs) {
+      await toolchains.configureToolchains(
+        run.version,
+        run.distributionName,
+        run.jdkHome,
+        undefined
+      );
+    }
+
+    expect(fs.existsSync(toolchainsFile)).toBe(true);
+    const contents = fs.readFileSync(toolchainsFile, 'utf-8');
+
+    for (const run of runs) {
+      expect(contents).toContain(`<id>${run.id}</id>`);
+      expect(contents).toContain(`<jdkHome>${run.jdkHome}</jdkHome>`);
+    }
+    // Exactly one <toolchain> entry per run – no duplicates, none dropped.
+    expect((contents.match(/<toolchain>/g) || []).length).toBe(runs.length);
+  }, 100000);
 });

dist/setup/index.js

@@ -81751,7 +81751,6 @@ const path = __importStar(__nccwpck_require__(16928));
 const core = __importStar(__nccwpck_require__(37484));
 const io = __importStar(__nccwpck_require__(94994));
 const constants = __importStar(__nccwpck_require__(27242));
-const util_1 = __nccwpck_require__(54527);
 const xmlbuilder2_1 = __nccwpck_require__(54697);
 function configureToolchains(version, distributionName, jdkHome, toolchainId) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -81759,7 +81758,6 @@ function configureToolchains(version, distributionName, jdkHome, toolchainId) {
         const id = toolchainId || `${vendor}_${version}`;
         const settingsDirectory = core.getInput(constants.INPUT_SETTINGS_PATH) ||
             path.join(os.homedir(), constants.M2_DIR);
-        const overwriteSettings = (0, util_1.getBooleanInput)(constants.INPUT_OVERWRITE_SETTINGS, true);
         yield createToolchainsSettings({
             jdkInfo: {
                 version,
@@ -81767,13 +81765,12 @@ function configureToolchains(version, distributionName, jdkHome, toolchainId) {
                 id,
                 jdkHome
             },
-            settingsDirectory,
+            settingsDirectory
-            overwriteSettings
         });
     });
 }
 exports.configureToolchains = configureToolchains;
-function createToolchainsSettings({ jdkInfo, settingsDirectory, overwriteSettings }) {
+function createToolchainsSettings({ jdkInfo, settingsDirectory }) {
     return __awaiter(this, void 0, void 0, function* () {
         core.info(`Creating ${constants.MVN_TOOLCHAINS_FILE} for JDK version ${jdkInfo.version} from ${jdkInfo.vendor}`);
         // when an alternate m2 location is specified use only that location (no .m2 directory)
@@ -81781,7 +81778,7 @@ function createToolchainsSettings({ jdkInfo, settingsDirectory, overwriteSetting
         yield io.mkdirP(settingsDirectory);
         const originalToolchains = yield readExistingToolchainsFile(settingsDirectory);
         const updatedToolchains = generateToolchainDefinition(originalToolchains, jdkInfo.version, jdkInfo.vendor, jdkInfo.id, jdkInfo.jdkHome);
-        yield writeToolchainsFileToDisk(settingsDirectory, updatedToolchains, overwriteSettings);
+        yield writeToolchainsFileToDisk(settingsDirectory, updatedToolchains);
     });
 }
 exports.createToolchainsSettings = createToolchainsSettings;
@@ -81867,19 +81864,21 @@ function readExistingToolchainsFile(directory) {
         return '';
     });
 }
-function writeToolchainsFileToDisk(directory, settings, overwriteSettings) {
+function writeToolchainsFileToDisk(directory, settings) {
     return __awaiter(this, void 0, void 0, function* () {
         const location = path.join(directory, constants.MVN_TOOLCHAINS_FILE);
         const settingsExists = fs.existsSync(location);
-        if (settingsExists && overwriteSettings) {
+        // The toolchains file is produced by a non-destructive merge (existing JDK,
-            core.info(`Overwriting existing file ${location}`);
+        // custom, and non-jdk toolchains are preserved – see generateToolchainDefinition),
-        }
+        // so it is always safe to write it. Unlike settings.xml, it is therefore not
-        else if (!settingsExists) {
+        // gated behind the `overwrite-settings` input; that would prevent subsequent
-            core.info(`Writing to ${location}`);
+        // setup-java runs from registering additional JDKs and silently drop the
+        // toolchain entries created by earlier runs.
+        if (settingsExists) {
+            core.info(`Updating existing file ${location}`);
         }
         else {
-            core.info(`Skipping generation of ${location} because file already exists and overwriting is not enabled`);
+            core.info(`Writing to ${location}`);
-            return;
         }
         return fs.writeFileSync(location, settings, {
             encoding: 'utf-8',

docs/advanced-usage.md

@@ -684,6 +684,8 @@ The `setup-java` action generates a basic [Maven Toolchains declaration](https:/
 ### Installing Multiple JDKs With Toolchains
 Subsequent calls to `setup-java` with distinct distribution and version parameters will continue to extend the toolchains declaration and make all specified Java versions available.
 
+Toolchain entries are always merged non-destructively: existing JDK, custom, and user-managed toolchains are preserved, and only an entry with the exact same `type` and `provides.id` is replaced. This behavior is independent of the `overwrite-settings` input, which only controls regeneration of `settings.xml`. As a result, running `setup-java` several times in the same job (for example in multiple steps or with multiple `java-version` values) accumulates every JDK in `toolchains.xml` instead of dropping previously registered entries.
+
 ```yaml
 steps:
 - uses: actions/setup-java@v5

src/toolchains.ts

@@ -5,7 +5,6 @@ import * as core from '@actions/core';
 import * as io from '@actions/io';
 import * as constants from './constants';
 
-import {getBooleanInput} from './util';
 import {create as xmlCreate} from 'xmlbuilder2';
 
 interface JdkInfo {
@@ -27,10 +26,6 @@ export async function configureToolchains(
   const settingsDirectory =
     core.getInput(constants.INPUT_SETTINGS_PATH) ||
     path.join(os.homedir(), constants.M2_DIR);
-  const overwriteSettings = getBooleanInput(
-    constants.INPUT_OVERWRITE_SETTINGS,
-    true
-  );
 
   await createToolchainsSettings({
     jdkInfo: {
@@ -39,19 +34,16 @@ export async function configureToolchains(
       id,
       jdkHome
     },
-    settingsDirectory,
+    settingsDirectory
-    overwriteSettings
   });
 }
 
 export async function createToolchainsSettings({
   jdkInfo,
-  settingsDirectory,
+  settingsDirectory
-  overwriteSettings
 }: {
   jdkInfo: JdkInfo;
   settingsDirectory: string;
-  overwriteSettings: boolean;
 }) {
   core.info(
     `Creating ${constants.MVN_TOOLCHAINS_FILE} for JDK version ${jdkInfo.version} from ${jdkInfo.vendor}`
@@ -68,11 +60,7 @@ export async function createToolchainsSettings({
     jdkInfo.id,
     jdkInfo.jdkHome
   );
-  await writeToolchainsFileToDisk(
+  await writeToolchainsFileToDisk(settingsDirectory, updatedToolchains);
-    settingsDirectory,
-    updatedToolchains,
-    overwriteSettings
-  );
 }
 
 // only exported for testing purposes
@@ -172,22 +160,19 @@ async function readExistingToolchainsFile(directory: string) {
   return '';
 }
 
-async function writeToolchainsFileToDisk(
+async function writeToolchainsFileToDisk(directory: string, settings: string) {
-  directory: string,
-  settings: string,
-  overwriteSettings: boolean
-) {
   const location = path.join(directory, constants.MVN_TOOLCHAINS_FILE);
   const settingsExists = fs.existsSync(location);
-  if (settingsExists && overwriteSettings) {
+  // The toolchains file is produced by a non-destructive merge (existing JDK,
-    core.info(`Overwriting existing file ${location}`);
+  // custom, and non-jdk toolchains are preserved – see generateToolchainDefinition),
-  } else if (!settingsExists) {
+  // so it is always safe to write it. Unlike settings.xml, it is therefore not
-    core.info(`Writing to ${location}`);
+  // gated behind the `overwrite-settings` input; that would prevent subsequent
+  // setup-java runs from registering additional JDKs and silently drop the
+  // toolchain entries created by earlier runs.
+  if (settingsExists) {
+    core.info(`Updating existing file ${location}`);
   } else {
-    core.info(
+    core.info(`Writing to ${location}`);
-      `Skipping generation of ${location} because file already exists and overwriting is not enabled`
-    );
-    return;
   }
 
   return fs.writeFileSync(location, settings, {