TeamCity 2026.1では、Agentを動かすJava環境の要件を満たさないと、登録画面へ進む前に失敗します。まず TeamCity公式のシステム要件 で、対象がOn-Premises 2026.1の記載であることを確認してください。

ここで混同しやすいのが、Agentの実行JDKとプロジェクトのコンパイル用JDKです。前者はTeamCity Agentプロセスを起動するためのJava 21、後者はビルドスクリプトやGradleなどが実際に使うJavaです。プロジェクト側の要件を満たしていても、AgentのJAVA_HOMEが古ければ登録前に止まります。

最低限、次を記録します。

java -version
echo "$JAVA_HOME"
uname -m
xcode-select -p

java -versionの出力、JAVA_HOME、Apple Siliconかどうか、macOSの版、空き容量、実行ユーザーを資産台帳へ残します。Apple Silicon対応を確認するだけでは不十分で、Xcode、依存パッケージ、署名環境が同じCPU前提で動くかも確認が必要です。

本番Agentはrootで常駐させません。root運用では、ビルドスクリプトや依存ツールにホスト全体への強い権限を与え、ワークスペースの削除範囲も広がります。管理者権限が必要な初期インストール、専用ユーザー作成、ディレクトリ所有権の設定だけを管理者が行い、通常のAgentプロセスは専用の非rootユーザーで実行します。

Java 21を入れたのにAgentが動かない場合

JAVA_HOMEがサービス起動時に引き継がれていない、手動シェルとlaunchdの環境変数が違う、Agentディレクトリの所有者が別ユーザーになっている、といった差を疑います。端末上のjava -versionだけで合格にせず、実際のAgentログに記録されたJavaパスを確認してください。

Agentの接続は、サーバーがMacへ新しいジョブを押し込む構成ではありません。Agentが設定されたサーバーURLへ接続し、認証後にジョブを受け取るモデルです。登録処理は TeamCity公式のクイックセットアップ と Agent設定の公式手順 に照合します。

Connected表示だけで本番投入すると、次の問題を見落とします。

• serverUrlが社内向けの名前で、Agentから名前解決できない
• HTTPSの証明書チェーンがMac側で信頼されていない
• 反向きプロキシがWebSocketや長時間接続を切断する
• authorizationTokenの誤設定で登録または認証が完了しない
• 出力方向の通信だけがファイアウォールで遮断される
• Agent名が自動生成のままで、台帳や障害対応と結び付かない

登録時は、固定したAgent名、受け入れ対象のサーバーURL、認証設定、プロキシ経路を記録します。サーバー側の認証済み状態、Agentログ、プロキシログの3点が同じ時刻を示して初めて、接続を合格とします。

TeamCity Cloud 2026.2のAgent導入・起動資料は、Cloud環境の仕組みを説明するものです。Cloudの統合資料 をOn-Premises 2026.1の機能表として扱わないでください。Cloud専用の自動化や既定動作を、社内サーバーへそのまま移植できるとは限りません。

Xcodeが認識されない原因は、Xcode本体ではなくCommand Line Toolsだけを入れていることです。Appleの Xcode Command Line Tools公式リファレンス でも、コマンドラインツールとXcodeの役割は分けて説明されています。iOSのアーカイブやシミュレーター試験を実行するノードでは、完全なXcode環境を確認してください。

単一バージョンならxcode-selectで既定パスを固定します。複数バージョンを同居させる場合は、次の3層を混ぜないことが重要です。

1. Path to Xcode：ビルド設定が使用するXcodeのパス
2. Agent Parameters：そのMacが持つツールチェーン情報
3. Agent Requirements：ジョブが要求する条件と、ノードが提示する条件の照合

TeamCityのXcodeビルド資料 と Agentの事前定義パラメーター を使い、ジョブの要求、Agentが報告する値、実際のツール出力を突き合わせます。

AgentはオンラインなのにXcodeビルドだけ失敗する場合

まず、失敗ログのXcodeパスと、xcode-select -pの結果が一致しているか確認します。次に、要求したXcode版の条件がAgent Requirementsにあり、対象ノードのAgent Parameterがその条件を満たしているか確認します。オンライン状態は、Xcodeのライセンス同意、シミュレーターの初回準備、証明書、依存関係の解決まで保証しません。

同一Agent上のビルドは、プロジェクト単位で完全に隔離されるとは限りません。TeamCityの安全に関する考え方に沿って、信頼できないプルリクエスト、通常のテスト、正式リリース署名を同じ本番ノードへ混在させない設計にします。

特に確認する項目は次のとおりです。

• checkout directoryがプロジェクトごとに予測可能な場所へ分かれている
• clean checkoutを実行した場合に古い生成物が消える
• DerivedData、依存キャッシュ、アーカイブの共有範囲が明確である
• 一時Keychainに必要な証明書だけを投入している
• ビルド終了後にKeychain、プロファイル、署名用環境変数を消去する
• ログへ証明書の秘密情報やトークンが出力されていない

Agent Poolの公式設定 を基準に、署名ノードを専用Poolへ分けます。非信頼コードを実行するジョブは、専用Macまたは別Poolへ退避させます。共有Macで済ませる設計は、購入台数を抑えられる一方、資格情報の残留調査と復旧作業のコストが増えます。

Mac Agentで署名資格情報とワークスペースを分ける方法

プロジェクト別のcheckout先、ビルド後の削除処理、専用Keychain、Pool単位の権限を同時に設計します。ディレクトリ一覧、Keychain内の証明書一覧、ビルドログ、削除後の残留確認を証拠として保存し、設定ファイルだけをレビューして終わらせないことが大切です。

TeamCity AgentをMacのログイン後だけ起動する構成にすると、再起動後に誰もログインしなければジョブを受けられません。企業の本番ノードでは、Macの再起動、Agentの自動起動、サーバーへの再接続、Xcodeの初回呼び出し、Keychainの利用可否を連続して検証します。

TeamCityのAgent起動プロパティ資料 は、起動設定を確認する際の公式資料です。ただし、Cloud 2026.2の説明をOn-Premises 2026.1の既定動作とみなしてはいけません。On-Premisesでは、実際のMac、実行ユーザー、launchd設定、ファイル所有権を現物で確認します。

確認手順は次の順番で十分です。

1. 専用ユーザーとAgentディレクトリの所有権を確認する
2. launchdのplistが意図したユーザーとパスを指しているか確認する
3. Macを再起動し、Agentログの開始時刻を保存する
4. TeamCity上で再接続とジョブ受付を確認する
5. Xcodeの情報取得、シミュレーター試験、アーカイブを実行する
6. 一時Keychainが期待どおり利用できるか確認する
7. 起動失敗時の通知と代替Agentへの切り替えを試す

ログインが必要な公式手順を、そのまま無人運用の証拠にしないでください。再起動後に手動ログインが必要なら、リリースPoolへの投入は保留にします。

実際の判定では、空のサンプルプロジェクトより代表的なPR、シミュレーター試験、アーカイブ、管理された署名タスクを使います。記録対象は、ジョブの成功率、待ち時間、ワークスペース清掃、再起動後の復帰、代替ノードへの引き継ぎです。

条件を満たすなら選ぶ構成

• Java 21がAgentプロセスのログで確認できるなら、登録検証へ進めます
• Xcodeの要求、Agent Parameter、実際のパスが一致するなら、そのPoolへ割り当てます
• 署名情報が一時Keychainへ限定され、終了後に消えるなら、管理対象のリリースジョブを許可します
• 再起動後に自動接続し、実ジョブが完了するなら、本番候補にします
• 待ち時間と失敗記録を継続的に取得できるなら、容量増設を判断します

条件を満たさないなら戻す構成

• Java 21をサービス環境で確認できないなら、登録を中止してJDKと所有権を直します
• Xcodeの要求とノード情報が一致しないなら、別Poolへ隔離するかルーティング条件を修正します
• 署名情報が残るなら、信頼できないジョブを止め、専用Macへ分離します
• 再起動後にログインが必要なら、リリースPoolへ入れず試験ノードに戻します
• 待ち時間や代替接管を記録できないなら、増設より先に監視と運用手順を整えます

固定Macを購入するか迷っている場合は、Mac miniの調達条件を比較する案内 と、遠隔ノードを含む構成を同じ基準で見積もります。必要なのはスペック表ではなく、チームの同時実行数、署名ジョブの分離、障害時の代替経路です。

KVMNODEの遠隔Macを使う場合も、最後に見るべきなのは「Macを借りられるか」ではなく、TeamCityの実ジョブを隔離環境で受け、再起動後に復帰し、署名情報を消去できるかです。自社購入のMac miniは長期の安定負荷や物理インターフェースが必要な場合に向きますが、初期費用、保守担当、固定容量、故障時の交換が負担になります。まず試験ノードを短期レンタルし、証拠がそろってから週単位、月単位、長期の容量へ移行するほうが、未検証のMacを複数台購入するより判断を誤りにくくなります。

本番に必要な実機をすぐ確保したい場合は、KVMNODEのMac環境 で独立ノードを試し、あなたのTeamCity、Xcode、署名手順に対して受け入れ記録を作成してください。長期の固定負荷、特殊な物理機器、社内で完結すべき規制要件がある場合は、自社Mac購入も候補に残すべきです。

最終更新：2026年8月30日。TeamCity On-Premises 2026.1・Cloud 2026.2の公式資料、およびApple DeveloperのXcode資料を基に確認しています。