プロジェクト管理者ガイド

基本的な TeamCity ワークフロー

次の図は、基本的な TeamCity ワークフローを示しています：

1. TeamCity サーバーは リポジトリ内の変更を検出します。

2. サーバーはこの変更をデータベースに書き込みます。

3. ビルド構成に添付された トリガーは、データベース内の関連する変更を検出し、ビルドを開始します。

4. トリガーされたビルドは ビルドキューに表示されます。

5. ビルドは、互換性のある無料のビルドエージェントに割り当てられます。

6. エージェントは、ビルド構成に記述されているビルドステップを実行します。 ステップの実行中、エージェントはビルドの進捗を TeamCity サーバーに報告します。 すべてのログメッセージ、テストレポート、コードカバレッジの結果がオンザフライで送信されるため、ビルドプロセスをリアルタイムで監視できます。

7. ビルドが完了すると、エージェントは ビルドアーティファクトをサーバーに送信します。

ステップ、構成、プロジェクト

TeamCity では、ビルドルーチンは次のブロックで構成できます：

プロジェクト

プロジェクト は、ユーザーが作成できる最大の TeamCity エンティティです。 プロジェクトには、子サブプロジェクト、スタンドアロンビルド構成、パイプラインが含まれます。

• ネストされたサブプロジェクトを追加して、構成とパイプラインを個別のカテゴリに整理できます。

• TeamCity の ユーザー権限の大部分はプロジェクトベースです。 これにより、個別のチームごとにプロジェクトを作成したり、独立したプロジェクトごとにユーザーグループを定義したりできます。

• プロジェクトは、 接続、 パラメーター 、アーティファクトストレージ、 クラウドエージェントプロファイル 、およびすべての子サブプロジェクト、構成、パイプラインと共有されるその他のエンティティを所有できます。 例: プロジェクトレベルで GitLab への接続を 1 回作成すると、このプロジェクトが所有するすべての構成またはパイプラインでこの接続を利用してリモートリポジトリにアクセスできるようになります。

• プロジェクトはビルド、テスト、デリバリーといったタスクを実行しません。 これらのタスクは、プロジェクトが所有するビルド構成とパイプラインによって実行されます。

ルートプロジェクト は、TeamCity によって自動的に作成される最上位プロジェクトです。 このプロジェクトは削除できず、サーバー全体の接続、パラメーター、クラウドエージェントプロファイル、アーティファクトストレージを作成できます。

ビルド構成

ビルド構成 とは、特定の順序で実行される一連のビルドステップのことです。 構成を使用することで、以下のことが可能になります。

• 必要な順序で手順を並べ替えます。

• 個々のステップを一時的に無効にします。

• ステップを実行する 条件を設定します。 条件が満たされない場合、対応するステップはスキップされます。 たとえば、ステップ 3 はステップ 2 が失敗した場合にのみ実行されるように設定でき、ステップ 4 は Windows エージェントでのみ実行されるように構成できます。

設定を テンプレートに変換することもできるため、新しい設定を手動で設定しなくても、簡単に複製して再利用できます。 複製後は、各コピーを個別にカスタマイズできます。

同じプロジェクトまたは異なるプロジェクトの構成を 1 つの 統合されたワークフローに組み込むこともできます。

ビルドチェーン

ビルドチェーン は、 スナップショット依存関係を介して相互接続された一連のビルド構成です。 単一のチェーンで、同じプロジェクトまたは別々のプロジェクトの構成をリンクできます。 チェーンは、必要なビルド構成まで部分的に実行できます。 たとえば、「テスト→ ビルド→ デプロイ」のチェーンでは、「デプロイ」フェーズをスキップできます。

詳細については以下の記事を参照してください: 依存関係をセットアップする | ビルドチェーン

パイプライン

パイプライン は、従来の ビルドに代わる軽量で使いやすい方法です。 各パイプラインには 1 つ以上のジョブが含まれ、各ジョブは一連のビルド手順を実行します。

パイプラインを使用すると、個別のビルド構成を作成したり、スナップショットの依存関係を介してリンクしたりすることなく、単一の画面で完全なマルチステージワークフローを設計できます。

必要なビルド構成まで実行できるビルドチェーンとは異なり、パイプラインは常にすべてのジョブを実行します。

パイプラインとビルド構成はどちらもプロジェクトによって所有されます。

詳しいガイダンスについては、 パイプラインとビルド構成およびビルドチェーンの比較 セクションを参照してください。

ジョブ

ジョブ とは、パイプラインの単一の要素であり、一連のビルドステップを 1 つずつ線形に実行します。 ビルド構成とは異なり、ジョブは追加の実行条件なしに、すべてのステップを実行します。

ジョブはパイプライン内でのみ作成でき、大規模なビルドチェーンの個々のビルド構成に似ています。

ビルドステップ

ビルドステップ は、定義済みのコマンドセットを実行するための重要な構成要素です。 これは、単一のコマンド（mvn test や gradle クリーンビルド など）または一連の操作（カスタム Python や Bash スクリプトなど）のいずれかになります。 ビルドステップは、部分実行ではなく、完全に実行されます。

ビルドステップは、ジョブまたはビルド構成にグループ化されます。

編集モードと表示モード

TeamCity の構成、パイプライン、プロジェクトを表示するときは、2 つのモードを切り替えることができます：

表示モード

通常の日常操作で使用する表示モードで、ビルド履歴を表示します。 ユーザーは個々のビルドに移動して、ビルドログの確認、このビルドとともにトリガーされた依存構成の表示、生成されたアーティファクトのダウンロードなどを行えます。 詳細については、 ユーザーガイドを参照してください。

編集モード

プロジェクトまたは構成の設定を変更できます: 構成済みのビルドステップ、有効または無効なビルド機能、ビルドトリガーなど。 ユーザーの 権限によっては、これらの設定の一部を利用できない場合があります。

2 つのモードを切り替えるには、右上隅にある 設定 トグルを使用します。

TeamCity は、手動で切り替えない限り、選択したモードを維持します。 つまり、1 つの構成の設定を表示 / 編集している場合、別の構成に移動すると、その設定も表示されます。

使用可能なプロジェクトおよび構成設定の詳細については、 プロジェクトの作成と編集 および ビルド構成の作成と編集。 のセクションを参照してください。

VCS ルート

VCS ルート は、TeamCity ←→ VCS リポジトリ通信の基盤です。 この不可欠な要素は、リポジトリのチェックアウト、コードソースのタグ付け、ビルドステータスの VCS への返信など、さまざまな操作を実行するために必要な VCS プロバイダーへの接続を定義します。

VCS ルートには次の情報が保存されます。

• TeamCity がリモートファイルをプルおよびプッシュするために使用するフェッチ URL とプッシュ URL。

• ブランチ情報: TeamCity がトラックする必要があるリポジトリブランチのリストと、デフォルト (メイン) のブランチ。

• 認証設定: TeamCity がリポジトリにアクセスするために使用する資格情報。

• チェックアウト設定: リモートファイルの保存方法と、サブモジュールをメインリポジトリと一緒にチェックアウトするかどうかを指定します。

• カスタムでは、デフォルトの 60 秒間隔を上書きできるポーリング設定を変更します。

VCS ルートに関連するセクションは、プロジェクト設定と構成設定の両方で使用できます。

ただし、構成はルートを所有することはありません。 構成に VCS ルートを「アタッチ」することはできますが、ルートは常にプロジェクトに保存されます (プロジェクトによって所有されます)。 この手法により、次のようになります。

• VCS ルートは複数の構成に接続できるため、複数のビルド構成が同じ認証およびチェックアウト設定で同じリポジトリにアクセスできます。

• 1 つの構成に複数の VCS ルートを接続できるため、1 つの構成内で異なるリポジトリを操作できます。

• VCS ルートを編集すると、それを使用するすべての構成に影響します。 VCS ルート設定を変更する場合、このルートを複製し、更新された設定をこの新しいクローン内に保存して、元のルートを変更しないというオプションがあります。 これにより、1 つのビルド構成をカスタマイズしながら、このルートを共有する他の構成には影響を与えずに済みます。

VCS ルートは、リモートリポジトリを使用するすべてのビルド構成に不可欠な部分ですが、多くのシナリオでは TeamCity がルートを自動的に生成するため、新しいビルド構成ごとに手動で作成する必要はありません。 例については、 このチュートリアルを参照してください。

ビルド機能

ビルド機能は、追加の機能を有効にするために任意のビルド構成に追加できる機能です。 たとえば、 コミットステータスパブリッシャー ビルド機能は、コードファイルを保存する VCS に TeamCity ビルド結果を公開し、 調査の自動割り当て は最新の変更によってビルドを破損させたユーザーを特定して、これらの課題の解決を自動的にタスクとして割り当てます。 構成されたビルド機能は、削除することなくいつでも一時的に無効にできます。

関連記事: ビルド機能の追加

ブランチの操作

TeamCity では、ブランチごとに異なるビルドルールをセットアップできます。 たとえば、新しい変更が現れるたびに「本番」ブランチをビルドし、「開発」ブランチを毎晩ビルドし、「サンドボックス」ブランチを無視することができます。 これを行うには、ブランチのスペックとフィルターを指定する必要があります。

変更の収集

プロジェクトのセットアップが完了すると、TeamCity は ブランチ仕様に含まれるリポジトリブランチにコミットされたすべての新しい変更に関する情報を受け取れます。 新しい変更の通知は、次のいずれかの方法で受信されます。

定期的なリポジトリポーリング

デフォルトでは、TeamCity は 60 秒ごとに、プロジェクトでターゲットになっているすべての VCS リポジトリを自動的にポーリングします。 このアプローチの欠点は次のとおりです。

• 非効率性 - TeamCity は、新しい変更がほとんどないリポジトリも含め、すべてのリポジトリを常にポーリングし続けます。

• パフォーマンス - TeamCity サーバーに大量のプロジェクトがある場合、定期的なポーリングによって大きな負荷が発生する可能性があります。

• 遅延 — ユーザーが変更をコミットした後、その変更が TeamCity 構成の 保留中の変更タブに表示されるまで、最大で一分待つことがあります。 ユーザーは アクション構成メニューを使用して、プロセスを手動でトリガーすることもできます:

  

ポーリング間隔を変更するには、 TeamCity サーバーの一般設定に移動します。 個々の構成でこの値を上書きするには、VCS ルートの 最小ポーリング間隔設定を編集します。

ウェブフック

ウェブフックを使用すると、VCS ホスティングプロバイダーは新しい変更を TeamCity に通知できます。 デフォルトのポーリングメカニズムと比較して、この動作には次の利点があります。

• 効率性 - 変更が現れると、TeamCity サーバーが変更通知を受け取ります。

• スピード - 変更通知はコミットされるとすぐに届きます。

欠点としては、Webhook ではリポジトリ / プロジェクトごとに手動で設定する必要があることです。

コミットフックが構成されているプロジェクトでは、フックが機能しなくなった場合に備えて、バックアップメカニズムとしてリモートリポジトリをポーリングし続けます。 ただし、フック通信が成功するたびに、ポーリング間隔は自動的に 2 倍になります。 TeamCity がこの間隔を延長する最大値は 4 時間で、最小間隔は 15 分です。 スケジュールされたポーリングでコミットフックをトリガーしなかった変更が見つかった場合、TeamCity はポーリング間隔をデフォルト値にリセットします。

関連記事: VCS コミット後フックの設定

ビルドを自動的に開始

TeamCity ユーザーは、構成の右上隅にある 実行 ボタンから、いつでも新しいビルドをトリガーできます。 新しいビルドを自動的に開始するには、 トリガーを構成する必要があります。

TeamCity は、スケジュールされたビルドの時間ベースのトリガー、新しいコミットの変更ベースのトリガー、他の構成の補完時にビルドを起動するトリガーなど、さまざまなイベントに基づいて新しいビルドを開始するための各種トリガーを提供します。

関連記事: ビルドトリガーの構成

アーティファクト

アーティファクトはビルド中に生成されるファイルです。 これらのファイルは、次の場合に使用できます。

• TeamCity ユーザーは、 ビルド結果ページ からダウンロードできます。

• 他の TeamCity ビルドは、 チェーンでデータを渡す を使用してこれらのファイルをインポートできます。

ビルドアーティファクトとして使用できるようにするファイルを選択するには:

1. 構成設定を開き、 一般設定設定タブに移動します。

2. アーティファクトパス プロパティを設定します。 まず、必要なファイルを生成するビルドを実行します。 次に、「最新のビルドからファイルを選択」ボタンをクリックして、手動でパスを入力する代わりに、ドロップダウンメニューからファイルを選択できるようになります。

関連記事: ビルドアーティファクト

依存関係をセットアップする

実際の CI/CD パイプラインでは、多くの場合、複数のスタンドアロンステージが組み合わされます。 たとえば、「ビルド」、「テスト」、「ステージングへのデプロイ」構成 (またはジョブ) は、独立して実行することも、順番に実行することもできます。

TeamCity では、これらのスタンドアロンエンティティ間の関係を作成するための複数のオプションを利用できます。

ビルドチェーン

ビルドチェーンは、 スナップショット依存関係を使用して相互接続された従来の TeamCity 構成のコレクションです。

スナップショット依存関係は右から左への関係です。 たとえば、構成 "B" が構成 "A" に依存関係を持つ "A -> B" チェーンでは、"A" が先に適切なビルドを生成するまで "B" は実行できません。 ビルドが "suitable" であるかの基準はセットアップによって異なります。詳細については、 適切なビルドセクションを参照してください。 同時に、"A" は新しい "B" ビルドをトリガーせずに個別に実行できます。

ミッションクリティカルなシナリオでは、プロジェクトに最近変更がない場合でも、常に最新のアップストリーム構成ビルドを強制するように依存構成を設定できます。

パイプライン

プロセスの各フェーズを表すジョブを使用してチェーンを構築する簡略化された代替手段です。 これは、小規模で複雑でないワークフロー（ルーチン全体で約 10 ～ 15 フェーズ）に推奨されるオプションです。

ビルドチェーンにリンクされたビルド構成と比較すると、パイプラインには次の違いがあります。

• リンクできるのは、同じパイプラインに属するジョブのみです。 一方、ビルドチェーンでは、完全に別の TeamCity プロジェクトに属するビルド構成をリンクできます。

• 手動設定を必要とするスタンドアロンのアーティファクトとスナップショットの依存関係は利用できません。 現在のジョブに先行するジョブを選択すると、そのすべてのアーティファクトをインポートするかどうかを即座に選択できます。

• パイプラインは、依存関係に関係なくすべてのジョブを実行します。 ビルドチェーンにはより多くのカスタマイズオプションがあり、 部分的に実行できます。

完了ビルドトリガー

完了ビルドトリガーは左から右への関係を確立します。 たとえば、ビルドチェーンに似た "A -> B" シーケンスを作成できますが、鍵となる違いがあります: "B" は独立して実行できる一方で、新しい "A" ビルドごとに新しい "B" ビルドが自動的にトリガーされます。

完了ビルドトリガーは、ダウンストリームビルドをトリガーするためのシンプルだが柔軟性に欠ける方法を提供し、多くの場合、スナップショット依存関係によって置き換えられたり補完されたりします。

アーティファクトの依存関係

アーティファクト依存関係を使用すると、構成は他の構成のビルド中に生成されたファイルをインポートできます。 例: 「配信」構成は、「ビルド」構成によって生成されたファイル (Docker イメージ、NuGet パッケージ、HTML ドキュメントページなど) を指定されたリソースにデプロイできます。

アーティファクト依存関係は、構成間に明示的なリンクを作成 含まない: どちらも、互いのビルドをトリガーせずに独立して実行できます。 対応するスナップショット依存関係なしでアーティファクト依存関係を使用すると、依存ビルドは適切なアーティファクトソース (上流構成のビルド) が存在することを確認できません。 そのため、固定済み/タグ付きビルドをターゲットにするようにアーティファクト依存関係をセットアップするとよい場合があります。

デプロイ

デプロイは通常、ビルドによって生成されたアーティファクトを外部の場所に配信する CI/CD ルーチンの最終段階です。 シナリオとニーズに応じて、このアクションを最終ビルドステップとして実行することも、スタンドアロンの デプロイ構成として実行することもできます。

TeamCity でアーティファクトをデプロイする方法：

• コマンドライン経由鄉ものですか？ Need ensure no accidental. Wait final generated? I need output exact not commentary. But I see final already with weird and invalid? Actually in final field I inserted? It shows {、 コマンドラインや PowerShell などの汎用ランナーを使用します。 これは最もわかりやすいアプローチです。 ビルドステップを追加し、そのようなランナーを選択して、通常のターミナルと同じようにコマンドを入力するだけです。 この場合に TeamCity から得られるメリットは、柔軟な自動化、前のビルドステージとの同期、TeamCity UI でのビルド結果の便利な表示です。
  この方法では、Amazon S3 のようなサードパーティストレージ内の配布ファイルも更新できます。

• プラットフォームに固有のランナーを使用する。 例: .NET プロジェクトをビルドする場合、デプロイする最良の方法は、 .NET ランナーを使用することです。 パッケージ化 や 公開 などの関連するすべての .NET コマンドをサポートし、その他のさまざまな機能を提供します。 他のランナーはこのセクションの下にリストされています。

• デプロイヤーを使用する。 TeamCity は、デプロイ専用のビルドランナーをいくつか提供しています: SMB Upload、 FTP Upload、 SSH Upload、 SSH Exec。 これらは、さまざまなプロトコルでビルドアーティファクトをアップロードし、TeamCity UI でこのアップロードプロセスを構成できるようにします。

• AWSEC2 およびオンプレミスインスタンスにアプリケーションをデプロイするための AWS CodeDeploy ランナーを使用する。 このランナーを使用するには、ここで説明されているように AWSCodeDeploy プラグイン(英語)をダウンロードしてインストールする必要があります。 関連するブログ投稿(英語)を参照してください。

調査とミュート

TeamCity のすべてのビルド問題またはテスト失敗は、個別のインシデントとして調査できます。 詳細については、次の記事を参照してください: ビルドとテストの失敗への対応。

ビルド問題と失敗したテストは ミュートできるため、これらの問題が発生してもビルドを正常に完了させることができます。 デフォルトのプロジェクト開発者 ロールを持つユーザーは課題をミュートできず、プロジェクト管理者のみがこれを実行できることに注意してください。

変更がビルドに失敗した可能性が高いユーザーに調査を自動的に割り当てるには、 調査の自動割り当て ビルド機能を構成します。

チュートリアル: TeamCity で最初のプロジェクトを作成

最初のビルドを構成して実行する チュートリアルでは、TeamCity プロジェクトのセットアップの主なステージについて説明します: VCS 接続の確立、ビルドアクションのセットアップ、追加機能の構成、このプロジェクトへのユーザーの割り当てなど。