TeamCity 2019.1ヘルプ

ビルド構成テンプレート

概要

構成テンプレートを作成するを使用すると、ビルド構成設定の重複を排除できます。いくつかの類似の(必ずしも同一ではない)ビルド構成を持ち、各構成を編集せずに共通の設定を1か所で変更できるようにする場合は、それらの設定でビルド構成テンプレートを作成します。テンプレート設定の変更は、このテンプレートに関連付けられているすべてのビルド構成に影響します。

このプロジェクトとそのサブプロジェクト内のすべてのビルド構成に対して、プロジェクト内の既定のテンプレートを定義することができます。以下のセクションに詳細があります。

ビルド構成テンプレートはプロジェクト階層をサポートします。いったん作成されると、利用可能なテンプレートには現在のプロジェクトとその親からのものが含まれます。プロジェクトまたはビルド構成をコピーすると、ターゲットプロジェクトまたはその親のいずれにも属していないテンプレートが自動的にコピーされます。テンプレートが現在のプロジェクトまたはその親のいずれかに属している場合にのみ、ビルド構成をテンプレートに関連付けることができます。

ビルド構成テンプレートを作成する

ビルド構成テンプレートを作成する方法はいくつかあります。

  • 通常のビルド構成のように手動

  • 既存のビルド構成からの抽出:画面の右上隅のアクションボタンから利用可能な抽出テンプレートオプションがあります。ビルド構成からテンプレートを抽出すると、元の構成が自動的に新しく作成されたテンプレートに関連付けられるようになります。

プロジェクト用のデフォルトテンプレートの定義

デフォルトのテンプレートを使用すると、このプロジェクトとそのサブプロジェクト内のすべてのビルド構成に影響を与えることができます。

デフォルト・テンプレートドロップダウンメニューからテンプレートを選択することにより、プロジェクト管理の一般設定ページを使用して、プロジェクトのすべてのビルド構成をデフォルトのテンプレートに関連付けることができます。このオプションは、プロジェクトまたはその親で少なくとも1つのテンプレートが定義されている場合に使用できます。新しいビルド構成はすべて、デフォルトのテンプレート設定を継承します。

既存の構成の設定は保持されます。

定義されている場合、他のデフォルトテンプレートがサブプロジェクトで定義されていない限り、デフォルトテンプレートはこのプロジェクトのすべてのビルド構成とサブプロジェクトに影響します。デフォルトのテンプレートを使えば、すべてのプロジェクトのビルド設定を簡単に変更できます。

  • 特定のビルド機能をプロジェクトのすべてのビルド構成に追加する

  • すべてのビルド構成を特定のチェックアウトモードに切り替えます

  • デフォルトの障害状態を提供する

関連設定の変更

プロジェクト構成スキーマは、デフォルトのテンプレートに対応しています。

  • XML: project-config.xml ファイルには <default-template ref="...." /> 要素が含まれています。

  • DSL:プロジェクト構成に defaultTemplate = "..." メソッドが含まれています。デフォルトのテンプレートが構成されたサンプルプロジェクト構成を参照してください。

object Project : Project({     uuid = "2b241ffb-9019-4e60-9a3a-d5475ab1f312"     extId = "ExampleProject"     parentId = "_Root"     name = "Example Project"     defaultTemplate = "ExampleProject_MyDefaultTemplate"     ...     features {         ...     }     ... })

ビルド構成をテンプレートに関連付ける

既存のビルド構成をテンプレートに関連付けると、ビルド構成はテンプレートで定義されたすべての設定を継承し、競合がある場合、テンプレート設定はビルド構成の設定よりも優先されます(依存関係、パラメーター、および要件を除く)。テンプレートから継承された設定は上書きできます

テンプレートが現在のプロジェクトまたはその親のいずれかに属している場合にのみ、ビルド構成をテンプレートに関連付けることができます。少なくとも1つの関連するビルド構成を持つテンプレートは削除できません。最初に関連するビルド構成をデタッチする必要があります。

ビルド構成を複数のテンプレートに関連付けることも可能です。

ビルド構成を複数のテンプレートに関連付ける

テンプレートに添付アクションメニューを使用して、ビルド構成を複数のテンプレートに添付できます。アクションメニューでは、テンプレートを管理するアクションによりユーザーは次のことができます。

  • テンプレートの順序を変更します。これは、重複する設定の優先度とビルドステップの順序に影響します。優先度は、リストの上位にあるテンプレートの設定に与えられます。ビルド構成にアタッチされたテンプレート間で重複する場合、パラメーター名、IDの設定(ビルドステップ、トリガー、機能、アーティファクトの依存関係、および要件)、VCSルートまたはスナップショットの依存関係ソースビルド構成IDなどのエンティティに影響します。

  • 一部のテンプレートからビルド構成をデタッチします(ユーザーはデタッチするようにマークし、変更を適用する必要があります)。

  • 同じダイアログウィンドウでそれぞれ名前の付いたボタンを使用して、すべてのテンプレートからビルド構成をデタッチします。

ビルド設定ページでビルド構成に添付されているすべてのテンプレートを表示できます。

ビルド構成がアタッチされているすべてのテンプレートの設定は継承され、ビルド設定ページの表示/編集で継承元を表示できます。

ビルド構成がそのテンプレートの一部からデタッチされると、それらから継承されたすべての有効な(構成でオーバーライドされず、優先度の高いテンプレートによってオーバーラップされない)設定が構成にコピーされます。ビルド構成ロジックのコピーは、テンプレートの抽出と同じです。ビルド構成/プロジェクトを移動すると、ロジックはビルド構成がアタッチされているすべてのテンプレートをチェックします。

関連設定の変更

  • XML:ビルド構成が単一のテンプレートに添付されている場合、結果の構成XML形式は以前と同じままです( settings エレメントのref 属性)。多数のテンプレートに添付されている場合、それらへの参照は、次のように settings ノードの個別の要素に保存されます。

<inherits> <ref id="Template1_ExternalId" /> <ref id="Template2_ExternalId /> ..... </inherits>
  • DSL:Kotlin DSLが拡張されているため、ビルド構成定義内でユーザーは templates(vararg) メソッドを使用して外部IDまたはDSLテンプレートインスタンスのいずれかを受け入れることができます(ただし、それらの混合ではないため、DSLの内側と外側の両方で定義されたテンプレートが同じ構成で使用される場合、両方の外部IDを使用する必要があります)。古い template(...) メソッドとプロパティーを同じビルドタイプ定義内で複数回使用して、複数のテンプレートから継承されていることを示すことはできません :以前の実装に従って、このメソッドが使用されるたびに、以前のテンプレート外部IDをオーバーライドします。下位互換性のために保持されます。

テンプレートからビルド構成をデタッチする

ビルド設定ページのアクションメニューで利用可能なテンプレートから切り離すオプションを使用して、テンプレートからビルド構成デタッチすると、テンプレートのすべての設定がビルド構成にコピーされ、編集可能になります。

テンプレートから継承した設定の再定義

テンプレートに関連付けられているビルド構成は、そのすべての設定を継承します(UIでは継承としてマークされています)。継承された設定は関連付けられたビルド構成から削除できませんが、継承されたビルド手順、トリガー、ビルド機能、失敗条件、成果物の依存関係、およびエージェント要件は無効にすることができます。

テンプレートの設定を変更すると、このテンプレートに関連付けられているすべての設定に影響します。ただし、関連付けられているビルド構成でほとんどの設定を再定義することは可能です。

ほぼすべてのビルド構成設定(ビルド手順、パラメータービルドオプションなど )を再定義できます。唯一の例外は、スナップショットの依存関係と再定義できないチェックアウト規則です。

変更された設定は黄色の境界線で強調表示され、リセットボタンが変更された設定の右側に表示され、テンプレートの元の設定への変更を元に戻すことができます。

ビルド構成で継承されたパラメータを再定義すると、継承された名前と新しい値で保存されます。その後、テンプレート内でこのパラメータの名前を変更すると、ビルド構成内で元の名前と再定義された値を持つパラメータと、テンプレートから継承された名前を変更したパラメータの2つのパラメータになります。

パラメータ参照を使用する

上記のように設定を再定義するだけでなく、継承した設定の個別のフィールドをパラメータ参照を介して再定義することができます。

構成パラメーターの参照を紹介するには、テンプレートのテキストフィールドに %ParameterName% 構文を使用します。導入されると、このパラメーターは、値が必要であるとマークされているビルド構成テンプレートのパラメーターページに表示されます。

パラメータのデフォルト値を指定することも、値を指定しないでおくこともできます。その後、テンプレートに関連付けられているビルド構成でパラメータの実際の値を定義できます。

ビルドパラメータの設定も参照してください。

設定パラメータの使用例

チェックアウト規則によってのみ異なる2つの類似したビルド構成があるとします。たとえば、最初の設定のチェックアウトルールには +:release_1_0 => .、2番目の設定のチェックアウトルールには +:trunk => .を含める必要があります。他のすべての設定は同じです。両方のビルド構成に関連付けるテンプレートを1つ用意すると便利ですが、これは各ビルド構成のチェックアウト規則を別々に変更することを意味します。

これを行うには、以下の手順を実行します。

  1. それらの構成の1つからテンプレートを抽出します。

  2. テンプレート設定で、バージョン管理設定に移動し、VCSルートのチェックアウト規則ダイアログを開き、そこに入力する: %checkout.rules%

  3. 継承ビルド構成の場合は、構成設定ページを開き、パラメーターページで checkout.rules 構成パラメーターの実際の値を指定します。

  4. 2番目のビルド構成では、アクションテンプレートと関連付けるオプションを使用して、テンプレートを選択します。テンプレートとの関連付けダイアログで checkout.rules パラメーターに適切な値を指定します。関連付けをクリックします。

結果として、異なるチェックアウト規則を持つ2つのビルド構成がありますが、1つのテンプレートに関連付けられています。

これにより、設定パラメータを作成して、テキストフィールドを持つ任意のビルド設定からそれを参照できます。

テンプレートに前後のステップを含める機能

このステップがすべてのビルド構成ステップの前または後に実行されるように、テンプレートに共通のビルドステップを定義する必要がある場合があります。
特定のテンプレートに対して、そのようなステップを定義してから、ビルド構成ステップに関してそれらの配置を定義することが可能です。すべてのビルド構成手順は、ビルド手順を並べ替えるダイアログではプレースホルダーとして表されています。テンプレートステップは、このプレースホルダの前後に配置できます。

Reorder build steps

必要に応じて、テンプレートベースのビルド構成でビルド手順の順序をカスタマイズできます。

  • TeamCity Web UIを使用すると、テンプレートステップに関してビルド構成ステップの配置を変更できます。

  • バージョン設定を使用すると、テンプレートのステップに関するビルド構成ステップの配置を変更できるだけでなく、テンプレート自体のステップの順序を変更することもできます。

テンプレートから継承した設定を強制する

プロジェクト内のすべてのビルド構成にいくつかの設定を適用して、他のユーザーが再定義できないようにする場合、TeamCityはプロジェクト階層内のすべてのビルド構成にこの機能を提供します。たとえば、強制設定を使用すると、どこでもエージェント側のチェックアウトを設定したり、すべてのビルド構成に厳密な実行タイムアウトを設定したりできます。現在、ビルド機能、オプション、およびパラメーターを強制することができます。ビルド手順とビルド要件も適用できます。

プロジェクト階層にいくつかの設定を適用するには、これらの設定を使用してテンプレートを作成します。その後、システム管理者はこのテンプレートをプロジェクトの強制設定テンプレートとして設定できます。

Enforced settings template

適用された設定テンプレートは、そのすべての設定がプロジェクト階層のビルド構成に継承されるため、デフォルトテンプレートに似ています。違いは、これらの継承された設定を無効にしたり上書きしたりできないということです。

プロジェクトを特定の強制設定テンプレートに関連付けるには、システム管理者のロールが必要です。テンプレート自体は、テンプレートが定義されているプロジェクトを管理できるプロジェクト管理者によって編集できます。

適用設定テンプレートがプロジェクトで指定されていて、別のテンプレートがサブプロジェクトの適用設定として割り当てられている場合は、サブプロジェクトのテンプレートが優先されます。


関連事項:

管理者ガイド : ビルド構成の作成と編集 | ビルドパラメータの設定