マトリックスビルド
マトリックスビルド ビルド機能を使用すると、指定されたパラメーター値を反復処理し、すべての組み合わせに対してビルドを生成することで、ビルドのコレクションを定義できます。
例: 次のパラメーターで構成されたマトリックスビルドが与えられたとします。
マトリックスビルドがトリガーされると、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%に設定できます。より複雑なシナリオの場合は、行列パラメーターのさまざまな値に対してさまざまなタスクを実行するスクリプトを実行するビルドステップを定義できます。
アーティファクトの公開
マトリックスビルドを実行すると、生成されたすべてのビルドからのアーティファクトが親ビルドの同じ場所に集約されます。これにより、アーティファクトファイルが上書きされる可能性があります。
アーティファクトファイルの上書きを避けるため、ビルド機能設定でマトリックスビルドのアーティファクトをメインビルド内の別のディレクトリにグループ化するトグルが有効になっていることを確認してください。有効になっている場合、TeamCity は仮想ビルドによって生成されたアーティファクトを別の parameter=value ディレクトリに配置します。
また、アーティファクトパスでパラメーター参照を使用して、カスタムアーティファクトグループ化を実装することもできます。例: 次のパスは、すべての .jar ファイルを「Browser」および「Java」パラメーター値に基づいて名前が付けられたディレクトリに配置します。
その結果、アーティファクトは次のような名前のディレクトリに保存されます。
マトリックスビルドの実行
マトリックスビルドは、通常のビルドと同じ方法 ( 実行をクリックするか、ビルドトリガーを構成するか、REST API 呼び出しを行う) で実行できます。
マトリックスのビルドが開始されると、TeamCity は次のようにビルドを実行します。
マトリックスビルドを初めて実行すると、マトリックスパラメーター値のすべての組み合わせに対して新しい仮想ビルド構成が生成されます。マトリックスのビルドは、これらの生成されたスナップショットの依存関係の親構成のように効果的に動作します。
TeamCity は生成されたビルドを実行します。各ビルドはビルドキューに個別に追加され、ビルドの優先順位とエージェントの選択に関する通常のルールに従います。
最初に生成されたビルドの実行が開始されるとすぐに、TeamCity は親ビルド (事実上、生成されたビルドに依存関係を持つ一種の複合ビルド ) を開始し、生成されたすべてのビルドからビルド結果を集約します。
マトリックスの構築が完了すると、マトリックスビルドの概要タブで概要テーブルを表示できます。
マトリックスの一部のみをビルドする必要がある場合は、カスタムビルドを実行するのが便利な方法です (個別の組み合わせを実行するための専用 UI の TW-84312(英語) リクエストに賛成票を投じることもできます)。「カスタムビルドを実行する」ダイアログの「パラメーター」タブに切り替えて、必要なパラメーター値を指定します。(区切り文字としてコンマを使用します)。このダイアログでオーバーライドしなかったパラメーターは、マトリックスビルド機能で指定されたすべての値を循環します。
特に、マトリックスビルドでビルドトリガーを構成する場合、トリガー構成ダイアログのビルドのカスタマイズタブを構成して、トリガーされたビルドに使用されるマトリックスパラメーター値をカスタマイズできます。
マトリックスビルドの表示
マトリックス構築は 2 つの異なるレベルで表示できます。
親ビルド — 生成されたビルドを構成および整理します
マトリックスのパラメーター構成を定義します
すべてのビルドに共通の構成設定を定義します
ビルドのトリガーを担当します
ビルドの概要を表形式で提供します
個々のビルドの詳細な結果は含まれていません
生成されたビルド — パラメーター値の単一の組み合わせのビルドを表します
親ビルドから読み取り専用構成設定を継承します
親ビルドと同じビルドステップを持つ
特定のビルドからの詳細な結果を提供します
マトリックス内の特定のビルドにドリルダウンすると、ビルドに関する完全な情報が記載された典型的なビルドページが表示されます。ただし、ビルドは親ビルドから構成設定を継承し、特にこのビルド構成を直接実行できないため、ビルド構成は読み取り専用です。
ビルドチェーン内のマトリックスビルド
マトリックスビルドは、通常のビルドと同様に、スナップショットの依存関係またはアーティファクトの依存関係を使用して連鎖させることができます。
通常のビルドにマトリックスビルドへの依存関係がある場合、その依存関係はマトリックスの親ビルドにリンクされます。生成されたビルドは読み取り専用であるため、依存関係を直接リンクすることはできません。それにもかかわらず、アーティファクトがそれぞれのビルドのパラメーターの組み合わせに従ってソートされていることを確認することで、生成されたビルドからアーティファクトを使用することができます。
このセクションでは、マトリックスビルドと通常のビルドの間にアーティファクトの依存関係が定義されているシナリオ 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(英語)。
カスタムビルドを実行するダイアログでは、新しい値にラベルを割り当てることはできません。
機能設定で指定された値にラベルがあり、その生の値にコンマが含まれている場合、カスタムビルドでラベルのみを使用してその値を参照することはできません。ラベル部分と生の値部分の両方を入力する必要があります。
関連ページ：
ビルド機能を追加する
ビルド機能は、追加の機能を有効にするために任意のビルド構成に追加できる機能です。例: ステータス発行者のコミットビルド機能は、コードファイルを保存する VCS に TeamCity ビルド結果を公開し、調査自動割り当ては最新の変更によってビルドが壊れたユーザーを識別し、これらの問題を解決するタスクを自動的に割り当てます。構成されたビルド機能は、削除することなくいつでも一時的に無効にできます。TeamCity ビルドの特徴：TeamCity には、構成に追加できる次のビルド機能が付属しています。A...
ビルドパラメーターの設定
パラメーターは、TeamCity 設定およびビルドスクリプトの構文を介して参照するペアです。パラメーター部分は、生の値 () にすることも、別のパラメーターへの参照 () を含めることもできます。パラメーター型：TeamCity は 3 種類のパラメーターをサポートしています。構成パラメーター — ビルド構成内で設定を共有することを主な目的とするパラメーター。これらのパラメーターを使用して、テンプレートから作成された構成やレシピを使用する構成をカスタマイズすることもできます。TeamCity は...
エージェント要件の設定
エージェントの要件は、ビルド構成を実行できるエージェントを指定する条件です。現在存在するすべての要件を表示して新しい要件を作成し、特定の構成を実行できるエージェントを確認するには、ビルド設定 | エージェント要件にアクセスしてください。エージェント要件ビデオガイド：要件構文：エージェント要件は式です。ここは、定義済みまたはカスタム (ユーザー定義) のビルドパラメーターです。例: エージェントにインストールされているオペレーティングシステムを報告するパラメーター。要件では、エージェントがこの特...
ビルドステップの実行条件
ビルドステップを構成するときに、一般的な実行ポリシーを選択し、TeamCity 2020.1 以降ではパラメーターベースの実行条件を追加できます。実行条件により、ビルドがより柔軟になり、次のような多くの一般的な使用例に対応します。デフォルトのブランチでのみステップを実行する、ブランチでのみステップを実行する、個人ビルドのステップをスキップする、ビルドステップの条件を追加メニューで使用可能な共通オプションをすばやく選択できます。または、その他の状態オプションを選択して、パラメーターベースの実行条件...
アーティファクトの依存関係
このページでは、あるビルドから別のビルドにファイルを渡すことができる TeamCity アーティファクトの依存関係の構成について詳しく説明します。例: 一般的なデプロイビルド構成は、他の (本番) 構成によって生成されたファイルを公開します。アーティファクトは以下から渡すことができます: 同じビルドチェーン内のターゲット構成の前に実行される構成。ターゲット構成と同じビルドチェーンの一部ではない個別の構成。同じ構成の以前のビルド。Web UI を使用したアーティファクトの依存関係の設定：ビルド構成...
一般設定を構成する
一般的なビルド構成設定：ビルド構成を作成するときは、次の設定を指定してください。名前ビルド構成名。ビルド構成 ID システム内のすべてのビルド構成とテンプレートにわたる構成の一意の ID は、ビルド構成名から自動的に生成されますが、手動で設定することもできます。ビルド構成にグローバルに一意の ID を指定し、その前にプロジェクト ID を付けるようにしてください。ビルド構成が作成された後、その ID を変更できます。また、ID を使用して、Web UI へのブックマークされたリンクと REST API...