マトリックスビルド
マトリックスビルド ビルド機能を使用すると、指定されたパラメーター値を反復処理し、すべての組み合わせに対してビルドを生成することで、ビルドのコレクションを定義できます。
例: 次のパラメーターで構成されたマトリックスビルドが与えられたとします。
マトリックスビルドがトリガーされると、 ブラウザー、 env.ShouldFail、 Java の指定された値のすべての組み合わせに対してビルドが実行され、次のビルドサマリーが生成されます (マトリックスビルドの 概要 タブ内)。
マトリックスビルドの構成
マトリックスパラメーターの構成
マトリックスビルド ダイアログは、マトリックスビルドのパラメーター定義を有効化します。各パラメーター定義は、パラメーターのお名前と関連付けられた値のリストで構成されます。られます。
例: 次のマトリックスパラメーターを使用してマトリックスビルドを構成するとします。
UI でマトリックスビルドを構成
ビルド機能の追加ダイアログから マトリックスビルドを選択します。
最初のパラメーターを次のように構成します。
パラメーター名を入力してください:
ブラウザー関連するパラメーター値を入力します:
Chrome,Firefox
2 番目のパラメーターを設定するには、「パラメーターの追加 」をクリックします。
パラメーター名を入力してください:
Javaラベル付きでパラメーター値を入力します:
JDK 17=>jdk-17とJDK 21=>jdk-21
保存をクリックして設定を確認し、マトリックス構築機能を有効にします。
Kotlin DSL でマトリックスビルドを構成
マトリックスパラメーターを構成するには、ビルド型構成の
機能ブロックにマトリックスブロックを追加し、その中に一連のパラメーターオブジェクトを作成します。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") ) ) } } })パラメーター名とパラメーター値を設定する場合:
パラメーター名は次のとおりです。
新しいパラメーターのお名前 (例:
ブラウザー)ビルド構成ですでに定義されている既存のパラメーターのお名前
定義済みのマトリックスパラメーター (定義済みマトリックスパラメーター を参照)
パラメーター値は、単一行のテキストと (任意で) いくつかの パラメーター参照 で構成されます。 値が長い場合や読みにくい場合は、ラベルを指定できます。ラベルは、マトリックスビルドの概要で生のパラメーター値の代わりに表示されます。
定義済みマトリックスパラメーター
TeamCity は、一般的なマトリックスビルドのユースケースの一部に対応するため、定義済みのマトリックスパラメーターを提供します：
パラメーター | 説明 |
|---|---|
| さまざまなチップセットアーキテクチャでビルドを実行できます。 エージェント要件と同等の制約を適用します: |
| 異なる JDK バージョンでビルドを実行できるようにします。 ドロップダウンリストから選択した各値 (たとえば、 |
| 異なるオペレーティングシステムでビルドを実行できるようにします。 エージェント要件と同等の制約を適用します: |
Kotlin DSL の例
Kotlin DSL での事前定義パラメーターの構成例:
エージェント要件の構成
エージェント要件 でマトリックスパラメーターを参照して、TeamCity が各値に適切なビルドエージェントを選択するようにできます
例: さまざまな種類のブラウザーに対して自動 UI テストを設定する場合、次の ブラウザー マトリックスパラメーターを定義できます。
エージェントが環境変数を定義してブラウザーのバージョンを指定するとします。
次のエージェント要件を定義して、対応する環境変数の存在に基づいて適切なエージェントを選択できます。
パラメーター名:
env.%Browser%条件:
存在する
構成でのマトリックスパラメーターの使用
マトリックスパラメーターを参照すると便利な状況は数多くあります。 以下にいくつかの例を示します。
条件付きビルドステップを使用すると、行列パラメーターの値に基づいて特定のビルドステップの実行を条件にすることができます。
ビルドに必要なリソースを参照するため。 例:
Javaマトリックスパラメーターの値がjava-17またはjava-21である場合、ビルドの JDK パスの定義でそれを直接参照できます。/usr/lib/jvm/%\Java%-openjdk-amd64特定の Java バージョンの Dockerfile をビルドするビルドステップがある場合は、生成されたイメージファイル名で
Javaマトリックスパラメーターを参照し、 イメージ名: タグ フィールドをmyapp:%Java%に設定できます。より複雑なシナリオの場合は、行列パラメーターのさまざまな値に対してさまざまなタスクを実行するスクリプトを実行するビルドステップを定義できます。
アーティファクトの公開
マトリックスビルドを実行すると、生成されたすべてのビルドからのアーティファクトが親ビルドの同じ場所に集約されます。 これにより、アーティファクトファイルが上書きされる可能性があります。
アーティファクトファイルの上書きを避けるため、ビルド機能設定で メインビルド内の別々のディレクトリにマトリックスビルドのアーティファクトをグループ化する トグルが有効になっていることを確認してください。 この場合、TeamCity は仮想ビルドで生成されたアーティファクトを別々の パラメーター=値 ディレクトリに配置します。
アーティファクトパスでパラメーター参照を使用して、カスタムのアーティファクトグループ化を実装することもできます。 例: 次のパスは、すべての .jar ファイルを「Browser」および「Java」パラメーター値に基づいて名前が付けられたディレクトリに配置します。
その結果、アーティファクトは次のような名前のディレクトリに保存されます。
マトリックスビルドの実行
マトリックスビルドは、通常のビルドと同じ方法 (実行 をクリックするか、ビルドトリガーを構成するか、REST API 呼び出しを行う) で実行できます。
マトリックスビルドが開始されると、TeamCity は次のようにビルドを実行します：
マトリックスビルドを初めて実行すると、マトリックスパラメーター値のすべての組み合わせに対して新しい仮想ビルド構成が生成されます。 マトリックスのビルドは、これらの生成されたスナップショットの依存関係の親構成のように効果的に動作します。
TeamCity は生成されたビルドを実行します。 各ビルドはビルドキューに個別に追加され、ビルドの優先順位とエージェントの選択に関する通常のルールに従います。
最初に生成されたビルドの実行が開始されるとすぐに、TeamCity は親ビルド (実質的には、生成されたビルドへの依存関係を持つ 複合ビルド の一種) を開始し、生成されたすべてのビルドからビルド結果を集約します。
マトリックスの構築が完了すると、マトリックスビルドの 概要 タブで概要テーブルを表示できます。
マトリックスの一部だけをビルドする必要がある場合は、カスタムビルドを実行すると便利です (個々の組み合わせを実行する専用 UI を求める TW-84312 リクエストに賛成票を投じることもできます)。 カスタムビルドを実行する ダイアログの パラメーター タブに切り替え、必要なパラメーター値を指定します (区切り文字としてコンマを使用します)。 このダイアログでオーバーライドしなかったパラメーターは、マトリックスビルド機能で指定されたすべての値を順に使用します。
特に、マトリックスビルドで ビルドトリガーを構成する場合、トリガー構成ダイアログの ビルドカスタマイズ タブを構成して、トリガーされたビルドに使用されるマトリックスパラメーター値をカスタマイズできます。
マトリックスビルドの表示
マトリックス構築は 2 つの異なるレベルで表示できます。
親ビルド — 生成されたビルドを構成および整理します
マトリックスのパラメーター構成を定義します
すべてのビルドに共通の構成設定を定義します
ビルドのトリガーを担当します
ビルドの概要を表形式で提供します
個々のビルドの詳細な結果は含まれていません
生成されたビルド — パラメーター値の単一の組み合わせのビルドを表します
親ビルドから読み取り専用構成設定を継承します
親ビルドと同じビルドステップを持つ
特定のビルドからの詳細な結果を提供します
マトリックス内の特定のビルドにドリルダウンすると、ビルドに関する完全な情報が記載された典型的なビルドページが表示されます。 ただし、ビルドは親ビルドから構成設定を継承し、特にこのビルド構成を直接実行できないため、ビルド構成は 読み取り専用です。
ビルドチェーン内のマトリックスビルド
マトリックスビルドは、通常のビルドと同様に、 スナップショット依存関係 または アーティファクト依存関係 を使用して連鎖させることができます。
通常のビルドにマトリックスビルドへの依存関係がある場合、その依存関係はマトリックスの親ビルドにリンクされます。 生成されたビルドは読み取り専用であるため、依存関係を直接リンクすることはできません。 それにもかかわらず、アーティファクトがそれぞれのビルドのパラメーターの組み合わせに従ってソートされていることを確認することで、生成されたビルドからアーティファクトを使用することができます。
このセクションでは、マトリックスビルドと通常のビルドの間にアーティファクトの依存関係が定義されているシナリオ マトリックスビルド 1 -> 通常ビルド 2－－? に焦点を当てます。 この場合、生成されたビルドからのアーティファクトの処理方法に注意する必要があります。
ビルドチェーンの例
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%
既知の制限事項
逆依存関係パラメーター
逆依存.*は、マトリックスビルドでは正しく機能しません。 関連する YouTrack チケット: TW-84730(英語)。マトリックスビルドが前のビルドに対するスナップショットの依存関係で構成されている場合、前のビルドのテスト結果がマトリックスビルドでレポートされますが、これは予期しない動作です。 関連する YouTrack チケット: TW-75412(英語)。
マトリックスビルドが前のビルドへのスナップショット依存関係で構成されている場合、チェーン内のすべての先行ビルドの時間が含まれるため、報告されるマトリックスビルドのビルド時間は長くなります。 これにより、タイムアウト設定の修正が必要になる場合があります。 関連する YouTrack チケット: TW-76020(英語)。
カスタムビルドを実行する ダイアログでは、新しい値にラベルを割り当てることはできません。
機能設定で指定された値にラベルがあり、その生の値にコンマが含まれている場合、カスタムビルドでラベルだけを使って参照することはできません。ラベルと生の値の両方を入力する必要があります。