setup-java@v6: JDK-Installation, Maven-Settings und Caches in GitHub Actions im Detail

setup-java@v6: Was am JDK-Endpunkt des Runners passiert

Die Action actions/setup-java ist in TypeScript geschrieben, steht unter MIT-Lizenz und liegt laut Repository-Metadaten bei 1994 Sternen und 866 Forks. Die im Material verzeichnete neueste Veröffentlichung ist v6.0.0 vom 24. August 2026, am selben Tag wurde auch in den Hauptzweig gepusht. Daneben existieren die älteren Tags v4.9.1 und v3.14.2 vom 4. August 2026, was darauf hindeutet, dass Wartungsversionen für zurückliegende Hauptversionen weiter gepflegt werden.

Laut README übernimmt die Action vier getrennte Aufgaben. Sie lädt eine gewünschte Java-Distribution herunter, entpackt sie und trägt sie in PATH sowie JAVA_HOME ein. Sie erzeugt Maven-Konfiguration, also settings.xml, Toolchain-Einträge und Eingaben für die GPG-Signierung. Sie registriert Problem-Matcher, damit javac-Diagnosen und unbehandelte Ausnahmen als Annotationen im Workflow-Log auftauchen. Und sie legt Caches an, sowohl für Abhängigkeiten der Buildwerkzeuge als auch für die JDK-Installation selbst.

Ausdrücklich genannt werden Java, Scala, Kotlin, Gradle, Maven und sbt als unterstützte Projekte. setup-java ist damit kein reiner JDK-Installer, sondern ein Bündel aus Installations- und Konfigurationsschritten, das man sonst mit mehreren run-Zeilen und einem eigenen Aufruf von actions/cache nachbauen müsste.

Von adopt zu temurin: die Aliase, die setup-java@v6 nicht mehr kennt

Wer einen Workflow mit distribution: adopt oder distribution: adopt-hotspot betreibt, erhält unter v6 einen Fehler. Die alten AdoptOpenJDK-Distributionen wurden entfernt. Das README verweist für diese Fälle auf temurin, für die OpenJ9-Variante auf semeru, wo früher adopt-openj9 stand. Der Bruch sitzt nicht in java-version, sondern im Distributionsnamen, und genau deshalb wird er bei einer Migration gern übersehen.

Umbenannt wurden außerdem drei Eingaben für das Maven-Publishing. Aus server-username wurde server-username-env-var, aus server-password server-password-env-var und aus gpg-passphrase gpg-passphrase-env-var. Die alten Namen funktionieren noch, erzeugen aber Warnungen. Der Zusatz env-var im Namen macht sichtbar, dass hier kein Geheimnis übergeben wird, sondern der Name jener Umgebungsvariablen, die das Geheimnis hält.

Für GPG-Passphrasen hat sich zusätzlich der Übergabeweg geändert. Statt eines gpg.passphrase-Server-Eintrags in der settings.xml reicht setup-java die Passphrase über gpg.passphraseEnvName weiter, was maven-gpg-plugin 3.2.0 oder neuer voraussetzt. Wer ein älteres Plugin einsetzt, muss dieses anheben, sonst endet der Signierschritt mit einem Fehler.

java-version, java-version-file und latest in setup-java

Die Versionsangabe kann direkt als Zahl stehen, aus einer Datei gelesen oder als latest aufgelöst werden. Der kürzeste Weg ist distribution: temurin mit java-version: '25'. Für die Datei-Variante akzeptiert java-version-file die Namen .java-version, .tool-versions und .sdkmanrc. Eine .sdkmanrc kann dabei auch die Distribution mitliefern, sofern der Eintrag ein erkennbares Anbieter-Suffix trägt, etwa java=21.0.5-tem.

Das Alias latest löst die neueste stabile GA-Version aus den Metadaten des Anbieters auf. Laut README funktioniert latest nicht zusammen mit java-version-file, nicht für Early-Access-Versionen und nicht mit distribution: jdkfile. Für reproduzierbare Builds bleibt eine feste Zahl die bessere Wahl, weil latest nach jedem Anbieter-Release ein anderes JDK bedeuten kann.

Die Versionssyntax deckt Hauptversionen wie 8, 11, 17, 21 und 25 ab, dazu Feature- und Patch-Versionen wie 11.0 oder 11.0.4 sowie mehrfeldrige Versionen nach JEP 322, etwa 18.0.1.1. Mit v6 kamen Temurin-Pakete vom Typ jdk+jmods hinzu sowie native musl-Artefakte für Alpine bei Dragonwell, Corretto, Zulu und Liberica. Verfügbarkeit, Paketvarianten, Architekturen und Versionsmetadaten unterscheiden sich je Anbieter, weshalb ein Blick in die Anbieterdokumentation vor dem Festlegen einer exakten Patch-Version sinnvoll bleibt.

verify-signature, Prüfsummen und die Lücke im Tool-Cache von setup-java

Unter v6 prüft setup-java heruntergeladene Archive automatisch gegen die Prüfsumme, sofern die Distribution eine solche veröffentlicht. Für Temurin und Microsoft ist die Paketsignaturprüfung standardmäßig aktiviert. Wer verify-signature: true für eine andere Distribution setzt, erhält einen Workflow-Fehler, weil die Action diese Kombination ablehnt.

Die Einschränkung mit der größeren Wirkung betrifft den Runner-Tool-Cache. JDKs, die dort bereits liegen, werden weder erneut heruntergeladen noch erneut verifiziert, und das gilt auch bei gesetztem verify-signature: true. Vorinstallierte JDKs der gehosteten Runner fallen genauso darunter wie ein JDK, das ein früherer Schritt im selben Job installiert hat. Wer Prüfung und Download erzwingen will, setzt force-download: true und nimmt dafür die längere Laufzeit in Kauf.

Verschärft wurde auch das Fehlerverhalten. Ungültige boolesche Werte, nicht unterstützte Kombinationen aus Distribution, Paket und Plattform sowie unterschiedlich viele IDs bei Maven-Toolchains führen zu gezielten Meldungen statt zu stillschweigendem Weiterlaufen. Bei Matrix-Builds spart das Zeit, weil das Log die Ursache benennt.

cache, cache-jdk und cache-read-only in setup-java@v6

Das Caching ist dreigeteilt. Der Abhängigkeits-Cache umfasst Verzeichnisse wie ~/.m2/repository für Maven und ~/.gradle/caches für Gradle, dazu sbt-Pfade. Hinzu kommen Wrapper-Caches für Maven- und Gradle-Wrapper-Distributionen. Der dritte Cache hält die JDK-Installation selbst.

Wird cache auf maven, gradle oder sbt gesetzt, aktiviert das den Abhängigkeits-Cache und implizit das JDK-Caching. Mit cache-jdk lässt sich das JDK-Caching unabhängig davon steuern. Neu in v6 sind cache-path für eigene Pfade und cache-read-only: true für reine Wiederherstellung, was bei Pull-Requests und Matrix-Jobs verhindert, dass jeder Zweig einen eigenen Cache schreibt.

Eine Änderung mit praktischer Nebenwirkung betrifft die Cache-Schlüssel: Sie berücksichtigen in v6 auch .mvn/extensions.xml und gradle.properties. Vorher konnte eine geänderte Gradle-Eigenschaft oder eine neue Maven-Erweiterung einen alten Cache zurückspielen, der diese Änderung nicht kannte. Wer nach dem Umstieg plötzlich Cache-Misses sieht, findet darin eine naheliegende Erklärung. Als Ausgaben liefert die Action cache-hit und cache-primary-key, womit sich das Trefferverhalten im weiteren Workflowverlauf verwenden lässt.

Maven-Settings, Toolchains und GRAALVM_HOME als Ausgaben von setup-java

Für Publishing-Workflows erzeugt setup-java eine settings.xml, die unter v6 mehrere Server-Credentials und eigene Repositories für die Abhängigkeitsauflösung tragen kann. Die Zugangsdaten stammen aus Umgebungsvariablen, deren Namen über die Eingaben mit env-var-Suffix übergeben werden. GPG-Schlüssel werden in ein isoliertes temporäres GPG-Verzeichnis importiert und nicht in den Standard-Keyring des Runners, wodurch ein späterer Schritt den Schlüssel nicht unbeabsichtigt mitbekommt.

Bei mehreren JDKs verwaltet die Action Maven-Toolchains und behält die Einträge über wiederholte Aufrufe hinweg, eine Verbesserung aus v5. Für GraalVM-Distributionen setzt v6 zusätzlich GRAALVM_HOME, nicht nur JAVA_HOME. Ein native-image-Build kann direkt auf diese Variable zugreifen, statt den Installationspfad selbst zu ermitteln.

Ebenfalls aus v5 stammen Detailverbesserungen am Buildverhalten: Die Transfer-Fortschrittsausgabe ist standardmäßig unterdrückt, die Maven-Settings werden nicht-interaktiv erzeugt, und javac-Fehler werden passend erkannt. Mit problem-matcher: false lässt sich die Annotation abschalten, wenn ein anderer Schritt dieselben Meldungen bereits auswertet.

setup-java oder ein fertiges JDK-Container-Image im Job

Die naheliegende Alternative ist ein Job, der vollständig in einem Container läuft, etwa mit container: eclipse-temurin:25-jdk. Damit existiert ein JDK, und damit endet die Unterstützung auch schon. Es gibt keinen Abhängigkeits-Cache für ~/.m2/repository, keine erzeugte settings.xml mit Server-Credentials, keine Toolchain-Verwaltung und keine Problem-Matcher für javac. All das müsste mit eigenen run-Schritten nachgebaut werden, inklusive Cache-Logik über actions/cache.

Der Unterschied zeigt sich am deutlichsten beim Maven-Publishing. setup-java übernimmt die Übergabe über server-username-env-var und server-password-env-var und schreibt daraus die settings.xml, während im Container-Ansatz die Datei selbst erzeugt werden muss. Wer dagegen nur einen einzelnen javac-Aufruf braucht und die JDK-Version im Image festnagelt, kommt ohne Downloadzeit schneller zum Ziel.

Eine Zwischenlösung bietet distribution: jdkfile zusammen mit jdk-file auf ein lokales, komprimiertes JDK-Archiv. Damit entfällt der Anbieter-Download samt Metadatenabfrage, ebenso die Prüfsummenprüfung gegen eine Anbieterquelle. Diese Kombination passt, wenn das JDK-Artefakt im eigenen Artefaktspeicher liegt und die Prüfkette intern abläuft.

Für wen sich der Umstieg auf setup-java@v6 lohnt

Die Versionslage ist eindeutig: v1 bis v4 gelten laut README als veraltet, zur Migration wird v6 empfohlen. Beim Umstieg von v5 sollten drei Dinge geprüft werden. Erstens, ob im Workflow noch distribution: adopt oder adopt-hotspot steht, was auf temurin beziehungsweise semeru geändert werden muss. Zweitens, ob ein älteres maven-gpg-plugin als 3.2.0 im Einsatz ist, weil gpg.passphraseEnvName sonst nicht greift. Drittens, ob selbst gehostete Runner mindestens v2.327.1 laufen, denn v5 hat die Action-Laufzeit von Node 20 auf Node 24 angehoben.

Wer einen dieser Punkte nicht prüfen kann, bleibt bei v5 und migriert gezielt. Für Projekte mit Maven-Publishing, mehreren JDKs in einer Matrix oder signierten Artefakten bringt v6 Verbesserungen, die über einen Versionssprung hinausgehen: der isolierte GPG-Speicher, die um .mvn/extensions.xml und gradle.properties erweiterten Cache-Schlüssel sowie die standardmäßig aktivierte Signaturprüfung für temurin und microsoft.

Weniger geeignet ist die Action für Workflows, die ohnehin containerbasiert arbeiten und ihre Toolchain im Image mitführen. Dort bliebe von setup-java nur der JDK-Download übrig, also genau der Teil, den ein Image bereits erledigt hat.

Redaktionelles Fazit

setup-java@v6 passt zu Maven-, Gradle- und sbt-Workflows, die JDK-Installation, Abhängigkeits-Cache und Publishing-Konfiguration aus einer Hand brauchen. Weniger passt es für Teams, die ihre JDK-Version im Container-Image festnageln und keine erzeugte settings.xml möchten, sowie für Workflows mit distribution: adopt oder adopt-hotspot, die erst auf temurin beziehungsweise semeru umgestellt werden müssen. Vor der Migration sollten die Distribution, eine maven-gpg-plugin-Version ab 3.2.0 und die Runner-Version v2.327.1 geprüft werden; danach lohnt ein Lauf mit force-download: true, damit Prüfsumme und Signatur gegen den Anbieter tatsächlich ausgeführt werden.

Offizielle Quellen

1. Official README
2. Project repository
3. Release notes