GitHub Actions setup-java v5.5.0の変更点|JDK署名検証・Kona・Maven修正

GitHub ActionsでJavaのCIを運用している場合、actions/setup-java v5.5.0への対応要否は、現在の参照方法とMavenの利用状況を確認すれば判断できます。

結論から言うと、TemurinまたはMicrosoft Build of OpenJDKを利用し、JDKの供給経路を強化したいチームは署名検証を有効化する価値があります。一方、JDK署名検証は初期状態では無効なので、更新しただけで既存ワークフローが失敗する可能性は高くありません。

注意したいのはMaven関連です。Maven 3.9以降やMaven Wrapperでは、ダウンロード進捗を表示しない設定が既定で追加されます。actions/setup-java@v5を参照している場合、2026年7月9日時点ではv5.5.0と同じ内容を受け取る状態であるため、YAMLを変更していなくてもログ表示が変わる可能性があります。GitHub公式Changelog上の日付は2026年7月8日です。(The GitHub Blog)

この記事では、JDK署名検証、Tencent Kona JDK対応、Maven修正、既存実装との互換性、導入条件、テスト時の注意点を整理します。

目次

GitHub Actions setup-java v5.5.0で何が変わったのか

v5.5.0では、セキュリティ機能だけでなく、複数JDKの扱いやMaven設定の安定性も改善されています。

主な変更点は次のとおりです。(The GitHub Blog)

変更点既定の動作既存ワークフローへの影響
JDKアーカイブの署名検証無効明示的に有効化しない限り原則影響なし
Tencent Kona JDK対応distribution: konaで利用Konaを利用する場合のみ影響
set-defaultの追加true従来どおりJAVA_HOMEとPATHを更新
.sdkmanrcからディストリビューションを判定対応する識別子がある場合に判定バージョン管理ファイルとYAMLの不一致に注意
Mavenの転送進捗を非表示Maven 3.9以降、Maven Wrapperで有効Mavenログの出力量が減る
生成するsettings.xmlを非対話モード化<interactiveMode>false</interactiveMode>を設定入力待ちに依存した処理が失敗する可能性
toolchains.xmlの重複整理同じ種類・IDのJDKを重複登録しないセルフホストランナーで特に有効

なお、GitHub公式のChangelogには、v5.4.0で追加されたGraalVM Community対応、javac用Problem Matcher、Maven Wrapperのキャッシュ対応も併記されています。これらはv5.5.0で新たに追加された機能ではありません。v5.4.0以前から一気に更新する場合は、両方の差分を確認してください。(The GitHub Blog)

JDK署名検証でダウンロードしたJavaを検証できる

v5.5.0の中心的な変更は、ダウンロードしたJDKアーカイブに対する暗号学的署名検証です。

verify-signature: trueを指定すると、setup-javaはJDK本体に加えて分離署名を取得し、GPG公開鍵を使ってアーカイブを検証してからインストールします。署名が不正、取得できない、信頼する公開鍵と一致しないといった場合は、ジョブが失敗します。(The GitHub Blog)

署名検証に対応するディストリビューション

v5.5.0で署名検証に対応しているのは、次の2種類です。

distribution対応状況
temurin対応
microsoft対応
kona非対応
その他のディストリビューション非対応

非対応のディストリビューションでverify-signature: trueを指定すると、検証を黙って省略するのではなく、エラーとして終了します。検証したつもりで未検証のJDKを利用してしまう状態を防ぐ設計です。(The GitHub Blog)

Temurinで署名検証を有効にする設定例

供給経路の固定も重視する場合は、v5.5.0タグではなく、公式が示している完全なコミットSHAを指定します。

- name: Set up Temurin 21
  uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a # v5.5.0
  with:
    distribution: temurin
    java-version: '21'
    verify-signature: true
    cache: maven

verify-signatureの初期値はfalseです。v5.5.0に更新しただけでは署名検証は始まらないため、利用する場合は明示的にtrueを設定する必要があります。(GitHub)

独自の公開鍵を指定する方法

組織で信頼するGPG公開鍵を管理している場合は、verify-signature-public-keyを指定できます。

- name: Set up Java with a managed public key
  uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
  with:
    distribution: temurin
    java-version: '21'
    verify-signature: true
    verify-signature-public-key: ${{ secrets.JDK_VERIFY_PUBLIC_KEY }}

指定するのは、鍵IDやファイルパスではなく、ASCII Armor形式の公開鍵本文です。複数行の改行が欠落するとインポートに失敗するため、GitHub Actionsへ登録した値が正しい形式で渡されることをテストしてください。

また、この入力は信頼する公開鍵を置き換えるためのものです。署名ファイルの取得先を任意のURLへ変更する設定ではありません。(GitHub)

署名検証を導入する前の確認条件

署名検証を有効にする前に、次の条件を確認します。

確認項目判断基準
ディストリビューションtemurinまたはmicrosoftを使用している
GPGコマンドセルフホストランナーでgpg --versionが成功する
ネットワークJDK本体と分離署名の両方を取得できる
公開鍵組み込み鍵を使うか、正しい公開鍵本文を指定している
テスト環境JDKが未キャッシュの状態でも実行確認できる
アクション参照タグまたはコミットSHAの運用方針を決めている

実装ではgpgコマンドを直接呼び出して検証します。そのため、特にセルフホストランナーでは、GPGがインストールされ、PATHから実行できることを事前に確認する必要があります。(GitHub)

キャッシュ済みJDKでは署名検証が実行されないことがある

署名検証のテストで特に失敗しやすいのが、ツールキャッシュの存在です。

対応するJDKがランナーのツールキャッシュにあり、setup-javaがそれを再利用した場合、新しいアーカイブをダウンロードしません。ダウンロードがなければ、アーカイブに対する署名検証も実行されません。

したがって、verify-signature: trueでジョブが成功しただけでは、署名検証経路を確認できたとは限りません。これはsetup-javaのキャッシュ確認とダウンロード処理の順序から分かる実装上の注意点です。(GitHub)

検証テストでは、次のいずれかを行います。

  • 新しいエフェメラルなセルフホストランナーを使う
  • ツールキャッシュに存在しないJDKバージョンで試す
  • ログでアーカイブのダウンロードと署名検証が実行されたことを確認する
  • テスト用ブランチで誤った公開鍵を指定し、想定どおり失敗することを確認する

共有ランナーのツールキャッシュを無理に削除すると、ほかのジョブへ影響する可能性があります。検証専用の一時ランナーを使う方法が安全です。

JDK署名検証だけではアクション自体を保護できない

verify-signatureが検証するのは、setup-javaがダウンロードするJDKアーカイブです。ワークフローが読み込むsetup-javaのコード自体を固定する機能ではありません。

サプライチェーン対策を重視する場合は、次の2つを分けて考えます。

  • setup-javaを完全なコミットSHAで固定する
  • setup-java内でverify-signature: trueを指定し、JDKアーカイブを検証する

GitHub公式も、移動するv5参照より、正確なバージョンタグまたは完全なコミットSHAを使う方法を案内しています。最も厳格に固定する場合は、v5.5.0のSHAである0f481fcb613427c0f801b606911222b5b6f3083aを使用します。(The GitHub Blog)

Tencent Kona JDKをGitHub Actionsで利用できる

v5.5.0では、新しいディストリビューションとしてTencent Kona JDKが追加されました。

基本的な設定は次のとおりです。

- name: Set up Tencent Kona JDK
  uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
  with:
    distribution: kona
    java-version: '21'

公式実装で対象となる主な条件は次のとおりです。(GitHub)

項目対応範囲
Javaメジャーバージョン8、11、17、21
Linuxx64、Arm64
macOSx64、Arm64
Windowsx64
パッケージJDKのみ
リリース最新の安定版
JDK署名検証v5.5.0では非対応

Windows Arm64、JREパッケージ、任意の過去パッチバージョンを前提にしたワークフローには、そのまま適用できません。

特に再現性を重視するビルドでは、「Java 21の最新安定版」だけで十分なのか、特定のパッチバージョンまで固定する必要があるのかを先に判断してください。Kona対応は、既存プロジェクトを一律にKonaへ移行するためというより、次のような用途に向いています。

  • 本番環境でTencent Kona JDKを採用している
  • TemurinとKonaの両方で互換性テストを行いたい
  • 中国市場向け環境を含むベンダー差異を検証したい
  • Arm64環境でKonaの動作を確認したい

TemurinとKonaをマトリクスで検証する例

strategy:
  matrix:
    distribution:
      - temurin
      - kona

steps:
  - name: Set up Java
    uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
    with:
      distribution: ${{ matrix.distribution }}
      java-version: '21'
      verify-signature: ${{ matrix.distribution == 'temurin' }}

  - name: Run tests
    run: ./mvnw verify

Konaでは署名検証が未対応なので、すべてのディストリビューションへ一律にverify-signature: trueを設定すると失敗します。マトリクスを使う場合は、対応するディストリビューションだけで有効化してください。

Mavenのログと設定ファイルに既定動作の変更がある

v5.5.0で既存ワークフローへ最も目に見える影響を与えるのは、Maven関連の変更です。

ビルド結果そのものより、ログ監視、トラブルシューティング、生成される設定ファイルへ影響するため、Mavenを利用しているチームは確認が必要です。

Mavenのダウンロード進捗が既定で非表示になる

setup-javaは、Maven 3.9以降およびMaven Wrapperを利用する環境で、MAVEN_ARGSへ-ntpを追加します。-ntpは--no-transfer-progressの短縮形で、依存関係やプラグインを取得するときの転送進捗を非表示にします。(The GitHub Blog)

たとえば、従来のログに表示されていた次のような情報が減ります。

Downloading from central: ...
Progress (1): ...
Downloaded from central: ...

これにより、GitHub Actionsのログが読みやすくなり、保存されるログ量も抑えられます。一方、次のような仕組みでは影響が出る可能性があります。

  • Downloading fromなどの文字列を監視している
  • Mavenログを解析して依存関係の取得状況を集計している
  • プロキシや社内ミラーの遅延を進捗表示で調査している
  • ログのスナップショットテストを行っている

依存関係の解決方法や取得元が変わるわけではありません。変更されるのは主に転送中のログ表示です。

ダウンロード進捗を元に戻す方法

進捗表示が必要な場合は、show-download-progress: trueを指定します。

- name: Set up Java
  uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
  with:
    distribution: temurin
    java-version: '21'
    show-download-progress: true

ただし、この設定は既存のMAVEN_ARGSから-ntpを削除する機能ではありません。setup-javaが新たに-ntpを追加しなくなるだけです。

すでに環境変数やコマンドラインへ次のような設定がある場合は、別途削除する必要があります。

env:
  MAVEN_ARGS: "-ntp"

setup-javaは既存のMAVEN_ARGSを保持し、すでに-ntpが含まれていれば重複追加しません。(GitHub)

生成されるsettings.xmlが非対話モードになる

setup-javaが生成するMavenのsettings.xmlには、次の設定が追加されます。

<interactiveMode>false</interactiveMode>

これにより、Mavenがユーザー入力を待つ動作を抑止できます。CIが入力待ちのまま停止する事態を防ぎやすくなります。コマンドラインで指定する-Bと目的は近いものの、ダウンロード進捗を抑止する-ntpとは別の設定です。(The GitHub Blog)

次のような処理は、更新後に重点的に確認してください。

  • Maven Centralや社内リポジトリへの公開
  • GPG署名を伴うリリース
  • 認証情報が不足した場合の動作
  • 手動選択を前提にした独自Mavenプラグイン
  • 対話入力を要求する古いスクリプト

通常のCIで対話入力に依存する設計は避けるべきですが、これまで偶然動いていた処理が明確に失敗する可能性があります。

既存のsettings.xmlを維持したい場合は、overwrite-settings: falseを利用できます。初期状態では、setup-javaがユーザーの.m2配下へ設定ファイルを生成または上書きします。(GitHub)

toolchains.xmlの重複が整理される

複数のsetup-javaステップを実行したり、同じセルフホストランナーを長期間利用したりすると、~/.m2/toolchains.xmlに同じJDK情報が重複することがあります。

v5.5.0では、JDKツールチェーンの種類とIDを基準に重複を取り除きます。一方、ルート要素の属性や、JDK以外のカスタムツールチェーンは保持されます。(The GitHub Blog)

次のように、意図的に異なるJDKへ同じmvn-toolchain-idを使い回している場合は注意が必要です。

- uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
  with:
    distribution: temurin
    java-version: '17'
    mvn-toolchain-id: build-jdk

- uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
  with:
    distribution: temurin
    java-version: '21'
    mvn-toolchain-id: build-jdk

異なるJDKをMaven Toolchainsで選択するなら、IDも分けます。

mvn-toolchain-id: temurin-17
mvn-toolchain-id: temurin-21

セルフホストランナーへ導入する際は、更新前後のtoolchains.xmlを比較し、利用中のカスタムツールチェーンが残っていることを確認してください。ただし、認証情報を含む可能性があるsettings.xml全体をCIログへ出力してはいけません。

set-defaultを使って既定のJavaを変更せずに追加できる

従来のsetup-javaは、インストールしたJDKをJAVA_HOMEとPATHへ設定し、そのジョブの既定Javaとして利用する動作が基本でした。

v5.5.0では、set-default: falseを指定することで、現在の既定Javaを維持したまま、追加のJDKをセットアップできます。初期値はtrueなので、既存ワークフローの動作は変わりません。(GitHub)

- name: Set up default Java 17
  uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
  with:
    distribution: temurin
    java-version: '17'

- name: Install Java 21 without changing the default
  id: java21
  uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
  with:
    distribution: temurin
    java-version: '21'
    set-default: false

- name: Check both JDKs
  shell: bash
  run: |
    java -version
    "${{ steps.java21.outputs.path }}/bin/java" -version

set-default: falseでも、バージョン別のJAVA_HOME環境変数やsetup-javaのpath出力は利用できます。また、Maven Toolchainsへの登録も行われます。

そのため、set-default: falseは「JDKを何も設定しない」オプションではありません。JAVA_HOMEとPATHの既定値を変更しないための機能です。Mavenのsettings.xmlやtoolchains.xmlに関する処理まで無効にするものではない点に注意してください。(The GitHub Blog)

.sdkmanrcからJDKディストリビューションを判定できる

java-version-fileとして.sdkmanrcを指定した場合、Javaバージョン末尾の識別子からディストリビューションを判定できるようになりました。

たとえば、.sdkmanrcに次のような設定があるとします。

java=17.0.7-tem

-temはTemurinを表すため、次のようにdistributionを省略できます。

- name: Set up Java from SDKMAN configuration
  uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a
  with:
    java-version-file: .sdkmanrc

主な対応例は次のとおりです。(GitHub)

.sdkmanrcの識別子setup-javaのdistribution
temtemurin
semsemeru
zuluzulu
amzncorretto
msmicrosoft
oracleoracle
sapmchnsapmachine
jbrjetbrains
konakona
graal、graalcegraalvm

識別できない接尾辞の場合は、従来どおりdistributionの指定が必要です。また、.java-versionや.tool-versionsから同じ方法でディストリビューションを自動判定する機能ではありません。

YAMLと.sdkmanrcで異なるdistributionを指定しない

実装上、.sdkmanrcから認識可能なディストリビューションが取得された場合、その値がsetup-javaの処理へ採用されます。(GitHub)

たとえば、次のような不一致は避けてください。

  • .sdkmanrcの末尾が-tem
  • ワークフローではdistribution: zulu

バージョン管理ファイルとワークフローの設定が異なると、更新前後で利用するJDKベンダーの認識が変わり、調査が難しくなります。.sdkmanrcから判定させるならdistributionを省略し、YAMLで固定するなら両者を同じ値にそろえるのが安全です。

既存ワークフローへの互換性と対応要否

v5.5.0は、v5.4.0からの更新で大きな破壊的変更を伴うリリースではありません。ただし、参照方法やMavenの使い方によって確認優先度が異なります。

現在の状態対応優先度推奨対応
actions/setup-java@v5を使用高Mavenログと生成ファイルをすぐ確認する
@v5.4.0やコミットSHAで固定中PRでv5.5.0へ更新し、差分テストする
v4以前を使用高Node.js 24対応とセルフホストランナーのバージョンを確認する
Maven 3.9以降を使用高MAVEN_ARGSとログ解析を確認する
Maven Wrapperを使用高ダウンロード進捗の有無を確認する
TemurinまたはMicrosoftを使用中署名検証を有効化するか判断する
Konaを本番利用高対応OS、CPU、Javaバージョンを確認する
セルフホストランナーを使用高GPG、ツールキャッシュ、toolchains.xmlを確認する
Gradleのみを使用低Maven修正の影響は限定的。署名検証とJDK設定を確認する

v5.4.0からの更新ではNode.jsランタイムは変わらない

setup-java v5は、アクションの実行ランタイムとしてNode.js 24を使用します。ただし、v5.4.0もすでにNode.js 24を使用しているため、v5.4.0からv5.5.0への更新で新たにランタイムが変わるわけではありません。(GitHub)

一方、v4以前からv5.5.0へ更新する場合は、セルフホストランナーのバージョンが重要です。GitHub公式は、v5をセルフホストランナーで利用する場合、Actions Runner v2.327.1以降を必要条件として案内しています。(GitHub)

ランナーの更新が難しい環境では、setup-javaだけを先にv5へ変更せず、ランナー更新とセットで計画してください。

v5.5.0へ更新するときのテスト手順

本番ワークフローを直接更新するのではなく、専用ブランチまたはPull Requestで検証します。

setup-javaの利用箇所を洗い出す

リポジトリ内のワークフローを検索します。

grep -R "actions/setup-java@" .github/workflows

Reusable WorkflowやComposite Actionにsetup-javaをまとめている場合は、呼び出し先も確認してください。

特に記録しておきたい項目は次のとおりです。

  • 現在のタグまたはコミットSHA
  • distribution
  • java-version
  • java-version-file
  • Maven、Gradle、sbtのどれを使っているか
  • cacheの設定
  • mvn-toolchain-id
  • セルフホストランナーの有無
  • Mavenログを解析する処理の有無

検証用PRでv5.5.0のSHAへ固定する

テスト中にv5の参照先が変わらないよう、検証用PRでは完全なSHAを指定します。

uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a

問題がなければ、そのままSHA固定で運用するか、更新管理のしやすさを優先してv5.5.0タグにするかを決めます。

実際に使うOSとJDKの組み合わせでテストする

最低限、現在運用している組み合わせを再現します。

strategy:
  matrix:
    os:
      - ubuntu-latest
      - windows-latest
      - macos-latest
    java:
      - '17'
      - '21'

runs-on: ${{ matrix.os }}

すべてのOSを本番で使っていない場合、無理に増やす必要はありません。重要なのは、本番と同じディストリビューション、Javaバージョン、ビルドコマンド、キャッシュ設定で確認することです。

JavaとMavenの実行環境を記録する

LinuxまたはmacOSでは、次のような確認ステップを追加できます。

- name: Show Java and Maven environment
  shell: bash
  run: |
    java -version
    mvn -version
    printf 'JAVA_HOME=%s\n' "$JAVA_HOME"
    printf 'MAVEN_ARGS=%s\n' "${MAVEN_ARGS:-}"

確認するポイントは次のとおりです。

項目期待する結果
java -version想定するベンダーとメジャーバージョン
mvn -version想定するJavaを使用している
JAVA_HOMEset-defaultの設定どおり
MAVEN_ARGS既定では-ntpが追加されている
setup-javaの出力version、distribution、pathが想定どおり
ビルド成果物更新前と同じテスト・パッケージング結果

Mavenは通常時と障害調査時の両方を試す

次の2パターンを実行します。

通常運用に近い設定:

show-download-progress: false

障害調査を想定した設定:

show-download-progress: true

trueにしても進捗が表示されない場合は、リポジトリ、組織変数、ランナー環境、Mavenコマンドに-ntpが残っていないか確認します。

セルフホストランナーではファイル差分を確認する

セルフホストランナーでは、更新前に次のファイルをバックアップします。

~/.m2/settings.xml
~/.m2/toolchains.xml

更新後は、次の点を確認してください。

  • 必要なMaven Server設定が残っている
  • カスタムToolchainが残っている
  • 同じIDのJDKが不要に重複していない
  • interactiveModeの変更が想定どおり
  • リポジトリ認証やリリース処理が成功する

settings.xmlにはユーザー名、トークン、パスワードが含まれる可能性があります。ファイル全体をActionsログへ表示せず、必要な要素だけをローカルまたは安全な検証環境で確認してください。

更新時に起きやすい失敗

verify-signatureを指定しただけで検証済みだと判断する

キャッシュ済みJDKが再利用された場合、アーカイブのダウンロードと署名検証が行われないことがあります。未キャッシュ環境でも確認してください。

Konaで署名検証を有効にする

v5.5.0のKonaは署名検証に対応していません。verify-signature: trueを一律設定するとジョブが失敗します。

show-download-progressで既存の-ntpも消えると考える

show-download-progress: trueは、setup-javaによる自動追加を止める設定です。既存のMAVEN_ARGSやMavenコマンドにある-ntpは削除しません。

set-default:falseならMaven設定も変更されないと考える

この設定が抑止するのは、主にJAVA_HOMEとPATHの既定値変更です。Maven Toolchainsへの登録など、setup-javaのほかの処理は継続されます。

同じmvn-toolchain-idを複数のJDKへ使う

重複整理によって、意図したJDKが選択されない原因になります。Javaバージョンやベンダーごとに一意のIDを設定してください。

@v5なら内容が固定されていると考える

v5はメジャーバージョンの移動タグです。将来のv5系更新を自動的に受け取ります。変更管理を厳格にする場合は、バージョンタグまたは完全なコミットSHAを使用します。

v4から更新するのにランナーを確認しない

セルフホストランナーが古いと、Node.js 24を使用するv5系アクションを実行できません。setup-javaを変更する前に、Actions Runnerのバージョンを確認してください。

対応要否を判断して段階的に導入する

GitHub Actions setup-java v5.5.0は、多くの既存ワークフローでそのまま利用できます。ただし、何も確認せず更新するのではなく、影響する機能を切り分けることが重要です。

まず、.github/workflows内のsetup-java参照を検索してください。@v5を使っている場合は、Mavenのログ表示や生成ファイルがすでに変わっている可能性があります。

次に、v5.5.0の完全なコミットSHAを指定した検証用PRを作り、本番と同じJDK、OS、Mavenコマンドでテストします。セルフホストランナーでは、GPGの有無、JDKキャッシュ、toolchains.xmlの差分も確認します。

最後に、TemurinまたはMicrosoft Build of OpenJDKを利用しているなら、未キャッシュ環境で署名検証をテストしたうえでverify-signature: trueを導入します。Konaは署名検証の対象外であること、Mavenの進捗表示は必要に応じてshow-download-progressで調整することを運用手順へ明記しておくと、今後のトラブルを減らせます。

この記事を書いた人

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows/Office(Teams・Excel)からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

コメント

コメントする

目次