マトリックスビルド
マトリックスビルド ビルド機能を使用すると、指定されたパラメーター値を反復処理し、すべての組み合わせに対してビルドを生成することで、ビルドのコレクションを定義できます。
例: 次のパラメーターで構成されたマトリックスビルドが与えられたとします。
マトリックスビルドがトリガーされると、Browser、env.ShouldFail、Java の指定された値のすべての組み合わせに対してビルドが実行され、次のビルドサマリーが生成されます (マトリックスビルドの概要タブ内)。
マトリックスビルドの構成
マトリックスパラメーターの設定
マトリックスビルドダイアログを使用すると、マトリックス構築のパラメーターを定義できます。各パラメーター定義は、パラメーター名と関連する値のリストで構成されます。
例: 次のマトリックスパラメーターを使用してマトリックスビルドを構成するとします。
UI でマトリックスビルドを構成する
ビルド機能の追加ダイアログからマトリックスビルドを選択します。
最初のパラメーターを次のように構成します。
パラメーター名を入力してください:
Browser関連するパラメーター値を入力します:
Chrome,Firefox
2 番目のパラメーターを設定するには、「パラメーターの追加」をクリックします。
パラメーター名を入力してください:
Javaパラメーター値をラベル付きで入力します:
JDK 17=>jdk-17およびJDK 21=>jdk-21
保存をクリックして設定を確認し、マトリックス構築機能を有効にします。
Kotlin DSL でのマトリックスビルドの構成
マトリックスパラメーターを構成するには、ビルド型構成の
featuresブロックにmatrixブロックを追加し、その中に一連のparamオブジェクトを作成します。package _Self.buildTypes // Other imports not shown import jetbrains.buildServer.configs.kotlin.matrix object Build : BuildType({ // Other code blocks not shown features { matrix { param( "Browser", listOf( value("Chrome"), value("Firefox") ) ) param( "Java", listOf( value("jdk-17", label = "JDK 17"), value("jdk-21", label = "JDK 21") ) ) } } })パラメーター名とパラメーター値を設定する場合:
パラメーター名は次のとおりです。
新しいパラメーター名 (たとえば、
Browser)ビルド構成ですでに定義されている既存のパラメーター名
事前定義されたマトリックスパラメーター ( 事前定義された行列パラメーターを参照してください)
パラメーター値は、1 行のテキストと (オプションで) いくつかのパラメーター参照で構成されます。値が長い場合や読みにくい場合は、ラベルを指定できます。ラベルは、マトリックス構築の概要に生のパラメーター値の代わりに表示されます。
事前定義された行列パラメーター
TeamCity は、一般的なマトリックス構築のユースケースの一部をカバーする事前定義されたマトリックスパラメーターを提供します。
パラメーター | 説明 |
|---|---|
| さまざまなチップセットアーキテクチャでビルドを実行できます。 エージェント要件と同等の制約を適用します: |
| 異なる JDK バージョンでビルドを実行できるようにします。 ドロップダウンリストから選択した各値 (たとえば、 |
| 異なるオペレーティングシステムでビルドを実行できるようにします。 エージェント要件と同等の制約を適用します: |
Kotlin DSL の例
Kotlin DSL での事前定義パラメーターの構成例:
エージェント要件の設定
エージェント要件のマトリックスパラメーターを参照して、TeamCity が各値に対して適切なビルドエージェントを選択できるようにすることができます。
例: さまざまな種類のブラウザーに対して自動 UI テストを設定する場合、次の Browser マトリックスパラメーターを定義できます。
エージェントが環境変数を定義してブラウザーのバージョンを指定するとします。
次のエージェント要件を定義して、対応する環境変数の存在に基づいて適切なエージェントを選択できます。
パラメーター名:
env.%Browser%条件:
exists
構成でのマトリックスパラメーターの使用
マトリックスパラメーターを参照すると便利な状況は数多くあります。以下にいくつかの例を示します。
条件付きビルドステップを使用すると、行列パラメーターの値に基づいて特定のビルドステップの実行を条件にすることができます。
ビルドに必要なリソースを参照するため。例:
Javaマトリックスパラメーターの値がjava-17またはjava-21である場合、ビルドの JDK パスの定義でそれを直接参照できます。/usr/lib/jvm/%Java%-openjdk-amd64特定の Java バージョンの Dockerfile をビルドするビルドステップがある場合は、生成されたイメージファイル名で
Javaマトリックスパラメーターを参照し、イメージ名: タグフィールドをmyapp:%Java%に設定できます。より複雑なシナリオの場合は、行列パラメーターのさまざまな値に対してさまざまなタスクを実行するスクリプトを実行するビルドステップを定義できます。
アーティファクトの公開
マトリックスビルドを実行すると、生成されたすべてのビルドからのアーティファクトが親ビルドの同じ場所に集約されます。これにより、アーティファクトファイルが上書きされる可能性があります。
アーティファクトファイルの上書きを避けるには、マトリックスパラメーター値の組み合わせで定義されたディレクトリ名を使用して、生成されたアーティファクトを並べ替えることをお勧めします。例:
次に、アーティファクトのパスを次のように定義できます。
生成されたビルドからのアーティファクトは、別のディレクトリに書き込まれます。
マトリックスビルドの実行
マトリックスビルドは、通常のビルドと同じ方法 ( 実行をクリックするか、ビルドトリガーを構成するか、REST API 呼び出しを行う) で実行できます。
マトリックスのビルドが開始されると、TeamCity は次のようにビルドを実行します。
マトリックスビルドを初めて実行すると、マトリックスパラメーター値のすべての組み合わせに対して新しい仮想ビルド構成が生成されます。マトリックスのビルドは、これらの生成されたスナップショットの依存関係の親構成のように効果的に動作します。
TeamCity は生成されたビルドを実行します。各ビルドはビルドキューに個別に追加され、ビルドの優先順位とエージェントの選択に関する通常のルールに従います。
最初に生成されたビルドの実行が開始されるとすぐに、TeamCity は親ビルド (事実上、生成されたビルドに依存関係を持つ一種の複合ビルド ) を開始し、生成されたすべてのビルドからビルド結果を集約します。
マトリックスの構築が完了すると、マトリックスビルドの概要タブで概要テーブルを表示できます。
マトリックスの一部のみをビルドする必要がある場合は、カスタムビルドを実行するのが便利な方法です (個別の組み合わせを実行するための専用 UI の TW-84312(英語) リクエストに賛成票を投じることもできます)。「カスタムビルドを実行する」ダイアログの「パラメーター」タブに切り替えて、必要なパラメーター値を指定します。(区切り文字としてコンマを使用します)。このダイアログでオーバーライドしなかったパラメーターは、マトリックスビルド機能で指定されたすべての値を循環します。
特に、マトリックスビルドでビルドトリガーを構成する場合、トリガー構成ダイアログのビルドのカスタマイズタブを構成して、トリガーされたビルドに使用されるマトリックスパラメーター値をカスタマイズできます。
マトリックスビルドの表示
マトリックス構築は 2 つの異なるレベルで表示できます。
親ビルド — 生成されたビルドを構成および整理します
マトリックスのパラメーター構成を定義します
すべてのビルドに共通の構成設定を定義します
ビルドのトリガーを担当します
ビルドの概要を表形式で提供します
個々のビルドの詳細な結果は含まれていません
生成されたビルド — パラメーター値の単一の組み合わせのビルドを表します
親ビルドから読み取り専用構成設定を継承します
親ビルドと同じビルドステップを持つ
特定のビルドからの詳細な結果を提供します
マトリックス内の特定のビルドにドリルダウンすると、ビルドに関する完全な情報を含む典型的なビルドページが表示されます。ただし、ビルドは親ビルドから構成設定を継承し、特にこのビルド構成を直接実行できないため、ビルド構成は readonly です。
ビルドチェーン内のマトリックスビルド
マトリックスビルドは、通常のビルドと同様に、スナップショットの依存関係またはアーティファクトの依存関係を使用して連鎖させることができます。
通常のビルドにマトリックスビルドへの依存関係がある場合、その依存関係はマトリックスの親ビルドにリンクされます。生成されたビルドは読み取り専用であるため、依存関係を直接リンクすることはできません。それにもかかわらず、アーティファクトがそれぞれのビルドのパラメーターの組み合わせに従ってソートされていることを確認することで、生成されたビルドからアーティファクトを使用することができます。
このセクションでは、マトリックスビルドと通常のビルドの間にアーティファクトの依存関係が定義されているシナリオ MatrixBuild1 -> RegularBuild2 に焦点を当てます。この場合、生成されたビルドからのアーティファクトの処理方法に注意する必要があります。
チェーンのビルド例
2 つのステージを持つ通常の (非マトリックス) ビルドチェーンを考えてみましょう。
Build1 には、 Java パッケージを生成するように構成された Maven ビルドランナーがあります。ビルド構成の一般設定セクションのアーティファクトパスフィールドは、生成されたパッケージをアーティファクトとしてキャプチャーするように構成されています。
ch-simple/simple/target/*.jar => packagesBuild2 は、次のアーティファクトのルール設定を使用して、Build1 に対するアーティファクトの依存関係を使用して構成されています。
packages => dependencies
テストを複数のブラウザーと Java バージョンに拡張するには、Build1 をマトリックスビルドとしてリファクタリングし、次のブラウザーと Java バージョンの組み合わせをカバーする必要があります。
Build1 でマトリックスパラメーターを構成した後、アーティファクト設定も更新する必要があります。
Build1 で、ビルド構成の一般設定セクションのアーティファクトパスフィールドを変更して、集約されたアーティファクトをパラメーターの組み合わせで並べ替えます。
ch-simple/simple/target/*.jar => packages/%Browser%-%Java%
既知の制限
逆依存関係パラメーター
reverse.dep.*は、マトリックスビルドでは正しく機能しません。関連する YouTrack チケット: TW-84730(英語)。マトリックスビルドが前のビルドに対するスナップショットの依存関係で構成されている場合、前のビルドのテスト結果がマトリックスビルドでレポートされますが、これは予期しない動作です。関連する YouTrack チケット: TW-75412(英語)。
マトリックスビルドが前のビルドへのスナップショット依存関係で構成されている場合、チェーン内のすべての先行ビルドの時間が含まれるため、報告されるマトリックスビルドのビルド時間は長くなります。これにより、タイムアウト設定の修正が必要になる場合があります。関連する YouTrack チケット: TW-76020(英語)。
カスタムビルドを実行するダイアログでは、新しい値にラベルを割り当てることはできません。
機能設定で指定された値にラベルがあり、その生の値にコンマが含まれている場合、カスタムビルドでラベルのみを使用してその値を参照することはできません。ラベル部分と生の値部分の両方を入力する必要があります。
関連ページ：
ビルド機能を追加する
ビルド機能は、ビルド構成に追加して、実行中のビルドやビルド結果のレポートに影響を与えることができる機能の一部です。TeamCity ビルドの特徴：TeamCity には、構成に追加できる次のビルド機能が付属しています。AssemblyInfo パッチャー AssemblyInfo.cs ファイルに手動でパッチを適用することなく、アセンブリにビルド番号を自動的に設定できます。詳細 ... 自動マージ必要なブランチのビルドを追跡し、ビルドが構成された条件を満たした場合 (たとえば、ビルドが成功した場合...
ビルドパラメーターの設定
パラメーターは、TeamCity 全体で参照できるペアです。TeamCity には、次の 3 つの主要なパラメーター型があります。構成パラメーター — パラメーターの主な目的は、ビルド構成内で設定を共有することです。これらのパラメーターを使用して、テンプレートから作成された構成や meta-runner を使用する構成をカスタマイズすることもできます。TeamCity は、この型のパラメーターをビルドプロセスに渡しません (つまり、これらのパラメーターはビルドスクリプトエンジンからアクセスできません)...
エージェント要件
エージェント要件は、ビルド構成を特定のビルドエージェントで実行できるかどうかを定義する特別な条件です。エージェントプールによるグループ化とともに、ビルドをエージェントに配布する方法を柔軟に制御できます。特定のビルド構成の明示的なエージェント要件を作成するには、ビルド設定 | エージェント要件に移動し、新しい要件を追加するをクリックします。各要件は、特定のパラメーターの条件付きルールを表します。パラメーター名または値を入力している間、TeamCity は関連する提案を表示します。要件を一時的に無効...
ビルドステップの実行条件
ビルドステップを構成するときに、一般的な実行ポリシーを選択し、TeamCity 2020.1 以降、パラメーターベースの実行条件を追加できます。実行条件により、ビルドがより柔軟になり、次のような多くの一般的な使用例に対応します。デフォルトのブランチでのみステップを実行する、ブランチでのみステップを実行する、個人ビルドのステップをスキップする、ビルドステップの条件を追加メニューで使用可能な共通オプションをすばやく選択できます。あるいは、その他の状態オプションを選択して、パラメーターベースの実行条件...
カスタムビルドの実行
通常、ビルド構成ではビルドトリガーを使用して、必要なスケジュールに従って、または TeamCity がソースコード内の新しい変更を検出したときに新しいビルドを開始します。これらの自動的にトリガーされるビルドに加えて、TeamCity ではビルドを手動で実行し、必要に応じて設定をカスタマイズすることもできます。つまり、新しいプロパティの追加または既存のプロパティの変更、特定の変更の選択、ビルドのスケジュール、ビルドを実行するエージェントの選択などを行うことができます。TeamCity には、カスタ...
コンポジットビルド構成
複合ビルド構成は、複数の通常のビルド構成をトリガーし、結果を 1 か所で追跡するように設計された「ステップレス」構成です。重要なポイント：複合構成では、実際の構築ルーチンは実行されません。複合構成では、依存関係からすべての情報が集約され、一元的な方法で表示されます。複合ビルドはビルドキュースロットを占有せず、エージェントを実行する必要もありません。ビルド構成タイプを切り替えるには、「構成設定 | 一般」タブに移動します。サンプル：このチュートリアルでは、複数のビルド構成を作成し、1 つのビル...