コントローラーの更新後、旧Javaで動いていたMac Agentがまとめてオフラインになり、iOSの配布ジョブまで止まることがあります。
最短の安全策は、先にプラグインとノードを棚卸しし、隔離したMac AgentでJava 21、再接続、実際のXcodeパイプラインを検証してから、コントローラーを更新し、タスクを段階的に移すことです。プロジェクトが必要とする旧JDKは、Agent JVMとは分けて残せます。
本記事は、JenkinsコントローラーまたはMac AgentがJava 17で稼働しているプラットフォームチーム、iOS CI/CDを止めずにJenkins LTSを更新したいIT責任者向けです。予備のMac、灰度環境、リモート復旧手段がない場合は、原地更新を避ける判断材料として利用してください。
最終更新：2026年9月3日。Jenkins公式のJavaサポート方針、2.555系アップグレードガイド、ノード管理資料を基に確認しています。
移行開始日に行う資産棚卸し
まず、Jenkinsのバージョン、コントローラーJVM、すべてのMac AgentのJVM、接続方式、ラベル、起動ユーザーを一覧化します。Jenkins公式のJavaサポート方針では、LTS 2.555.1以降について、コントローラーとAgentのJVMにJava 21またはJava 25が必要とされています。
ここで混同しやすいのが、次の4種類の実行環境です。
| 対象 | 役割 | 移行時の確認 |
|---|---|---|
| コントローラーJVM | Jenkins本体の実行 | 対象LTSが要求するJavaを確認 |
| Agent JVM | MacとJenkins間の通信 | JAVA_HOMEと起動経路を確認 |
| プロジェクトJDK | Javaのコンパイルやテスト | ジョブ単位で旧JDKを選択 |
| Xcodeツールチェーン | iOS/macOSのビルド、テスト、署名 | Xcode、Keychain、権限を実ジョブで検証 |
Macがオンライン表示でも、再起動後にAgentが戻るとは限りません。SSH、launchd、WebSocketなどの接続方式と、ログインシェルで設定した環境変数が一致するかを、Jenkinsのノード管理資料に沿って確認します。
アップグレード前の基準線とプラグイン確認
対象をJenkins LTS 2.555.1へ移す場合、コアだけでなく、認証、資格情報、Pipeline、ノード情報を扱うプラグインを確認します。LTSの変更点は公式2.555アップグレードガイドと変更履歴で確認し、プラグインの互換性を推測だけで判断しないことが重要です。
アップグレード前には、次の証拠を保存します。
- コントローラー設定、ジョブ定義、資格情報のバックアップ
- 各Mac Agentのラベル、実行者、起動パラメーター
JAVA_HOME、PATH、Xcode選択状態、作業ディレクトリ- 成功済みのXcodeビルド番号とログ
- 現行Jenkins、Agent JVM、プロジェクトJDKのバージョン
注意：ロールバック対象を「Jenkins全体」と一括りにしないでください。コントローラー、Agent JVM、プラグイン、ジョブのルーティングは別々に戻せるよう、変更単位を分けて記録します。
ノード上のJava確認は、次の最小限で足ります。
/usr/libexec/java_home -V
java -version
echo "$JAVA_HOME"
出力例は環境によって異なりますが、確認すべきなのは、Agent起動時に実際に呼ばれるJavaのパスと、Jenkinsのノード情報に表示されるJVMが一致していることです。ノード監視の情報を補助的に見る場合は、Versions Node Monitorsの説明も参照します。
隔離MacでのJava 21試行
最初の一台は、署名・配布の本番ジョブから外したMacを選びます。Java 21をインストールした後、Agent専用の起動設定でJavaの絶対パスまたはJAVA_HOMEを指定します。JenkinsのAgent利用ガイドにある接続方式と、実際のmacOS起動方式を照合してください。
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
"$JAVA_HOME/bin/java" -jar agent.jar
上記は起動経路の考え方を示す最小例です。実運用では既存の接続引数を維持し、Javaのパスだけを変更します。ログインシェルで成功しても、launchdやSSH経由では別の環境になるため、起動後にコントローラー側でAgentの接続時刻、JVM情報、ラベルを確認します。
確認項目は、登録、切断後の再接続、Mac再起動後の自動復帰、作業ディレクトリの再生成です。ここで一つでも未確認の項目があれば、コントローラーの更新へ進めません。
Xcodeパイプラインと署名境界の検証
次に、ソース取得、依存関係の復元、Xcodeビルド、テスト、成果物の保存までを含む代表ジョブを実行します。Xcodeのコマンドライン操作はAppleのXcodeコマンドラインツール資料に合わせ、Java移行前後で作業ディレクトリ、権限、ツール選択を比較します。
署名ジョブは、試行段階では非本番資格情報または読み取り専用の検証に限定します。Appleのコード署名に関する公式資料を基準に、Keychainのロック状態、実行ユーザー、署名証明書、プロビジョニング情報を別々に記録してください。
失敗した場合は、次の分類でログを残します。
- Agentが接続できない
- プラグイン呼び出しに失敗する
- プロジェクトJDKの選択が崩れる
- Xcodeまたは依存関係の処理に失敗する
- Keychainや署名権限で失敗する
Java 21へ変えたことだけを原因にせず、変更された環境変数と起動ユーザーを比較することで、ロールバック範囲を小さくできます。
コントローラー更新と段階的なタスク移行
隔離Mac、主要プラグイン、実ジョブが合格したら、アップグレード時間帯にコントローラーを対象Javaへ切り替え、目標LTSへ更新します。未移行のMacには専用ラベルを残し、互換性を確認できていないジョブが誤って割り当てられないようにします。
移行順は、非公開の検証ジョブ、通常のテスト、アーカイブ、署名・配布の順にします。各段階で、実ビルド、Agentの再接続、Mac再起動後の復帰、失敗時の切り戻しを確認してから次へ進みます。
| 移行段階 | 割り当てるジョブ | 継続条件 | 停止条件 |
|---|---|---|---|
| 隔離 | 検証用ジョブ | Agent接続とJava情報が一致 | 再接続または起動に失敗 |
| 小規模 | 非公開・テスト | Xcodeビルドと成果物保存が成功 | プラグインやJDK選択が不安定 |
| 本番前半 | 通常テスト・アーカイブ | 再起動後も自動復帰 | オフライン化が再現 |
| 本番後半 | 署名・配布 | 資格情報と署名結果を確認 | Keychainまたは配布処理に異常 |
既存ノードを一時停止する場合も、ノードを削除せず、ラベル、設定、起動パラメーターを保存します。これにより、Mac Agentだけを旧Javaへ戻すのか、コントローラーまで戻すのかを障害の範囲に応じて決められます。
本番一週目の運用基準
一度ビルドが成功しても、移行完了とは扱いません。Agentのオフライン、再接続、プラグイン例外、ビルド失敗の分類、無人再起動後の復帰を継続して記録します。
合格した組み合わせは、MacのOS、Java 21の起動パス、Xcode、環境変数、Agent接続方式、主要プラグインの組としてノード基準線へ固定します。予備ノードや切り戻し容量がない場合は、唯一の本番Macで原地試行せず、独立した遠隔Macを短期追加して灰度用にする方法を検討します。
NodeMiniのMac miniレンタルの構成案を比較対象にすれば、専用の試行ノードを置く場合に必要な接続方式、運用期間、既存ラベルとの分離条件を整理できます。既存のMac環境そのものを見直す場合は、Mac環境の注文・導入情報も確認できます。
移行判定チェックリスト
- [ ] コントローラーJVM、Agent JVM、プロジェクトJDK、Xcodeを別々に台帳化した
- [ ] Jenkins LTSと主要プラグインの互換性を公式資料で確認した
- [ ] Java 21を隔離MacのAgent起動設定へ明示した
- [ ] Agent登録、切断後の再接続、Mac再起動後の復帰を確認した
- [ ] 旧JDKを使うプロジェクトが個別設定でビルドできた
- [ ] Xcodeのビルド、テスト、成果物保存を実ジョブで確認した
- [ ] 本番署名を隔離し、Keychainの実行ユーザーを確認した
- [ ] 未移行ノードへの誤ルーティングを防ぐラベルを設定した
- [ ] Agentだけを戻す場合とコントローラーまで戻す場合を定義した
- [ ] 予備Macまたは遠隔復旧手段がない場合の代替策を決めた
現在のMacを唯一の本番ノードとして使い続ける方式は、停止して試せない、復旧操作を現地でしか行えない、灰度用の容量がないという欠点があります。Macを購入して増設する方法も、調達期間、資産管理、故障交換、遊休期間のコストを同時に抱えます。短期のJava 21検証や移行窓口だけが目的なら、NodeMiniで独立したMacをレンタルし、既存ノードを維持したまま試す方が、切り戻し条件を明確にしやすい構成です。
よくある判断
JenkinsのJava 21移行では、先にAgentを更新すべきですか？
先に対象Mac Agentを更新し、接続、再接続、再起動後の自動復帰、代表的なXcodeジョブを確認します。その後でコントローラーとJenkins LTSを更新し、非公開ジョブから段階的に切り替えます。順序を逆にすると、旧JavaのAgentが接続できず、切り戻し判断も難しくなります。
Mac上のJenkins AgentでJava 21を指定する方法は？
Agentプロセス専用のJAVA_HOMEまたはJava実行ファイルの絶対パスを起動設定へ明示します。macOSのログインユーザーが使うJavaと、launchdやSSHから起動するAgentの環境変数は一致しないことがあるため、起動経路ごとにjava -versionとJenkins上のノード情報を確認します。
Jenkins AgentをJava 21にしても、古いJavaプロジェクトをビルドできますか？
可能です。Agent JVMはJenkinsとの通信に使う実行環境であり、プロジェクトのコンパイル用JDKとは分離できます。Jenkinsのツール設定、ジョブの環境変数、またはビルドスクリプトで旧JDKを明示し、AgentのJAVA_HOMEをプロジェクト都合で上書きしない構成にします。
Jenkins更新後にMacノードがオフラインになった場合、どう戻しますか？
まずジョブの割り当てを停止し、コントローラー、Agent JVM、起動経路のどこで失敗したかを分離します。保存済みのAgent起動パラメーターと旧JDKのパスを使ってAgentだけを戻し、それでも復旧しない場合に限り、承認済みのJenkinsバージョンとコントローラー設定へ段階的に切り戻します。
複数のMac AgentをJava 21へ移行するときの進め方は？
同じmacOS、Xcode、認証方式、ラベルを持つ代表ノードを一台選び、まず隔離環境で検証します。合格後は非公開ジョブ、通常のテスト、アーカイブ、署名・配布の順にルートを移し、各段階で再接続と実ビルドを記録します。全台同時変更は障害範囲を広げるため避けます。
今週は、まず全Mac AgentのJVMと起動方式を台帳化し、隔離試行できるノードがあるかを確認してください。唯一の本番Macを止められない場合は、NodeMiniのMacレンタルを移行期間だけ利用し、Java 21とXcodeの実ジョブが通ってから、長期的な台数と運用方式を決めるのが安全です。