TeamCity On-Premises 2026.2 Help

チートシート: サーバーとエージェントマシンでの Java の更新

この記事では、エージェントマシンとサーバーマシンの Java アップデート手順について簡単に説明します。 詳細については、こちらの記事を参照してください。

Java 21 への移行

バージョン 2026.1 以降、TeamCity サーバーとエージェントの起動には Java 21 が必要です。 TeamCity サーバーは Java 21 のみをサポートしますが、TeamCity ビルドエージェントはより新しいバージョン (たとえば Java 25) で実行できます。 今後のリリースでは、最新の Java バージョンを正式にサポートする予定です。

アップグレード手順

アップグレードプロセスは、次の 2 つの重要なステップに要約されます。

  1. マシンに Java 21 をインストールします。

  2. TeamCity が新しいインストールを検出して使用することを確認します。

正確な手順はオペレーティングシステムによって異なります。

サーバーの更新

TeamCity Windows インストーラーとサーバー Docker イメージには Amazon Corretto 64 ビット版 Java 21 が含まれているため、手動でインストールする必要はありません。 TeamCity 2025.11 インストーラーを実行するだけで、必要な JDK が提供されます。

    TeamCity サーバーの .tar.gz アーカイブには Java が含まれていないため、手動でインストールする必要があります。 インストールする JDK はプラットフォームに合わせてください。 例: Amazon Corretto 21(英語) は、ARM64 と x86_64 の両方のアーキテクチャで動作する Linux と macOS 向けに異なるオプションを提供しています。

    Java 21 をインストールしたら、対応するインストールパスを JAVA_HOME または TEAMCITY_JRE 環境変数に割り当てます。 詳細な手順については、 こちらの StackOverflow スレッド(英語)を参照してください。

    • JAVA_HOME は、マシンのデフォルトの JDK を指定するグローバル変数です。 この変数を設定すると、 java -version ターミナルコマンドは対応するバージョンを指すようになります。

    • TEAMCITY_JRE 変数は TeamCity でのみ使用され、他のアプリケーションのデフォルトとして別の Java バージョンを使い続けることができます。

      エージェントの更新

      更新が必要なすべてのエージェント（ローカルエージェントと クラウドエージェントの両方を含む）を特定するには、 エージェント | 概要 | パラメーターレポート に移動し、 teamcity.agent.jvm.specification プロパティ値でエージェントをフィルタリングします。

      古いエージェントレポート

      REST API を使用して期限切れのエージェントをすべて見つけるには:

      # Find outdated local agents curl --location --request GET 'http://$SERVER_URL/app/rest/agents?locator=parameter:(name:teamcity.agent.jvm.specification,value:21,matchType:does-not-match)&fields=count,agent(id,name,connected,authorized,properties($locator(name:teamcity.agent.jvm.specification),property(name,value)))' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $TC_ACCESS_TOKEN' # Find outdated cloud profiles # Requires profiles to have at least one running agent curl --location --request GET 'http://$SERVER_URL/app/rest/cloud/profiles&fields=cloudProfile(id,name,images(cloudImage(id,name))&locator=image:(agent:(parameter:(name:teamcity.agent.jvm.specification,value:21,matchType:does-not-match))) \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $TC_ACCESS_TOKEN'

      ローカルエージェントの更新

      エージェントマシンをアップグレードする前に、潜在的な問題を回避するために既存のエージェントをアンインストールすることをお勧めします。

      1. エージェントのホームディレクトリに移動し、 アンインストール.exe を実行し、すべての「削除 ...」チェックボックスをオフのままにして、アンインストールを完了します。

      2. ブラウザーで TeamCity UI を開いてログインします。

      3. サイドナビゲーションバーで、 エージェント を開きます。

      4. エージェントのインストール をクリックし、JDK にバンドルされている .exe エージェントインストーラーをダウンロードします。

      5. 更新が必要なすべてのエージェントマシンでこのインストーラーを実行します。

      ビルドエージェントをサービスとして実行する場合は、 <エージェントホーム>/launcher/conf/ラッパー.conf ファイルの ラッパー.java.コマンド プロパティが必要な Java バージョンを指していることを確認してください。 詳細については、次の記事を参照してください: ビルドエージェント Windows サービスラッパーのアップグレード。

        エージェントマシンを更新するには、サーバーと同じ手順に従います。 または、 必要な JDK がバンドルされているエージェントアーカイブをインストールすることもできます。 その手順は次のとおりです。

        1. TeamCity UI で 管理 | エージェント JDK に移動します。

        2. 必要な Java バージョンをアップロードするには、 JDK を追加 をクリックします。

        3. TeamCity がターゲット JDK をダウンロードすると、対応するオプションが エージェント | エージェントをインストール | JDK 付きエージェントディストリビューション の下に表示されます。 エージェントの完全インストールには /JRE ディレクトリが含まれます。 エージェントを起動すると、 JAVA_HOME および TEAMCITY_JRE 環境変数によって返されるバージョンよりも、このディレクトリの Java が優先されます。

          クラウドエージェントの更新

          クラウドエージェントは、永続的なクラウドホストインスタンスまたはイメージから生成された一時的な仮想マシン上に配置できます。 VM の種類とクラウドホスティングプロバイダーによっては、更新手順が異なる場合があります。 たとえば、 EC2 AMI をターゲットとする TeamCity クラウドプロファイルの場合、次の手順が必要です：

          1. ローカルエージェントの更新 セクションの説明に従ってベースイメージを更新し、このエージェントが TeamCity に正常に接続することを確認してください。

          2. このベースイメージから新しい AMI を構築します。

          3. 新しい AMI をターゲットとするように TeamCity クラウドプロファイルとイメージを更新してください。

          Java の自動アップグレード

          Java がパッケージマネージャー経由でインストールされている場合 (Linux の apt-get など)、利用可能な最新バージョンに Java がサイレントに更新されることがあります。 このバージョンが TeamCity でサポートされている場合でも、特定の課題につながることがあります。 たとえば、すでに実行中のビルドエージェントは再起動する必要があります。そうしないと、正解の JDK を見つけられず、タスクの実行に失敗します。

          これらの潜在的な問題を回避するには、Java をインストールし、 JAVA_HOME および TEAMCITY_JRE 環境変数を手動で構成することをお勧めします。 例: 次のコマンドを実行して、 Ubuntu の無人アップグレード(英語)を無効にすることができます。

          # Check the unattended upgrade status systemctl status unattended-upgrades # Stop the service sudo systemctl stop unattended-upgrades # Disable the service sudo systemctl disable --now unattended-upgrades # Edit the configuration file sudo nano /etc/apt/apt.conf.d/20auto-upgrades # TODO: Insert or edit the 'APT::Periodic::Unattended-Upgrade "0";' line in the config file
          2026 年 9 月 11 日
          操作方法変更