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

基本的な 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 clean build など）または一連の操作（カスタム Python や Bash スクリプトなど）のいずれかになります。ビルドステップは、部分実行ではなく、完全に実行されます。

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

編集モードと表示モード

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

表示モード

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

モデルの編集

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

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

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

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

VCS のルート

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

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

• TeamCity がリモートファイルをプルおよびプッシュするために使用する 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 構成の保留中の変更タブに表示されるまで最大 1 分待つことができます。ユーザーは、アクション構成メニューを使用して、手動でプロセスをトリガーすることもできます。

  

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

Web フック

Webhook を使用すると、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」は実行できません。「適切な」ビルドの基準はセットアップによって異なります。詳細については、適切なビルドセクションを参照してください。同時に、「A」は新しい「B」ビルドをトリガーすることなく独立して実行できます。

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

パイプライン

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

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

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

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

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

ビルドトリガーの終了

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

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

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

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

アーティファクト依存関係は、構成間の明示的なリンクを作成しません。つまり、両方の構成は互いのビルドをトリガーすることなく独立して実行できます。対応するスナップショット依存関係なしでアーティファクト依存関係を使用する場合、依存ビルドは適切なアーティファクトのソース（上流の構成ビルド）が存在することを保証できません。そのため、ピン留めされたビルドまたはタグ付きビルドを対象とするアーティファクト依存関係を設定することをお勧めします。

デプロイ

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

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

• コマンドライン経由、コマンドラインや PowerShell などの一般的なランナーを使用します。これは最も簡単なアプローチです。ビルドステップを追加し、そのようなランナーを選択して、通常のターミナルと同じようにコマンドを入力するだけです。この場合、TeamCity から得られる利点は、柔軟な自動化、以前のビルドステージとの同期、および TeamCity UI でのビルド結果の便利な表示です。
  この方法では、Amazon S3 などのサードパーティストレージ内のディストリビューションファイルを更新することもできます。

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

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

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

調査とミュート

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

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

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

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

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