TeamCity 2020.1ヘルプ

ビルドパラメータの設定

ビルドパラメータは、設定を共有するための柔軟な手段と設定をビルドに渡す便利な方法を提供します。

ビルドパラメータの種類

ビルドパラメーターは、ユーザーが定義するかTeamCityによって提供される名前と値のペアで、ビルドで使用できます。

ビルドパラメータには3種類あります。

  • 環境変数env. 接頭辞を使用して定義)は、環境として生成されたビルドプロセスに渡されます。

  • システム・プロパティsystem. 接頭辞を使用して定義)は、サポートされているランナー(Ant、MSBuildなど)のビルドスクリプトに、ビルドツール固有の変数として渡されます。

  • 構成パラメータ(接頭辞なし)はビルドに渡されず、ビルド構成内で設定を共有することのみを目的としています。これらは、テンプレートに基づくビルド設定またはmeta-runnerを使用するビルド設定をカスタマイズするための主要な手段です。

TeamCityは一連の定義済みパラメータを提供し、管理者はカスタムパラメータを追加できます。

パラメータはさまざまなレベルで定義できます(優先順位の順に)。

  • 特定のビルド (カスタムビルドを実行するダイアログ経由)

  • ビルド設定またはビルド構成テンプレートパラメーターページ

  • プロジェクト設定パラメーターページ。これらは、プロジェクトとそのサブプロジェクトのすべてのビルド構成とテンプレートに影響する

  • ビルドエージェント (エージェント上の < Agent home >/conf/buildAgent.properties ファイル)

任意のテキスト設定でパラメーターを参照できます。 %parameter.name% 形式の文字列は、ビルド中に実際の値に置き換えられます。ビルドが定義されていないパラメーターを参照する場合、TeamCityはそれを暗黙のエージェント要件と見なします。ビルドは、このパラメーターが定義されているエージェントでのみ実行されます。

パラメータ名の制限

構成パラメーターの名前は、以下の要件を満たしている必要があります。

  • 次の文字のみを含む: [a-zA-Z0-9._-*]

  • ASCII文字で始まる

名前が上記の制限を満たさないパラメータへの参照は、暗黙の要件を作成しません。

ビルド構成でのビルドパラメータの定義

ビルド設定パラメーターページでは、ビルドの開始時にビルドスクリプトと環境に渡される必要なシステムプロパティと環境変数を定義できます。カスタムビルドの起動時に再定義できることに注意してください。

ビルド構成で定義されたビルドパラメーターは、この構成内でのみ使用されます。他の方法については、プロジェクトレベルとエージェントレベルのビルドパラメータを参照してください。

ユーザー定義のビルドパラメーター(システムプロパティまたは環境変数)は、次の形式を使用して他のパラメーターを参照できます。

%[env|system].property_name% For example: system.tomcat.libs=%env.CATALINA_HOME%/lib/*.jar

ビルド構成設定でのビルドパラメーターの使用

ほとんどのビルド構成設定では、実際の値を使用する代わりに、ビルドパラメーターへの参照を使用できます。ビルドを開始する前に、TeamCityはすべての参照を使用可能なパラメーターで解決します。解決できない参照がある場合、それらはそのまま残されます。それぞれの警告がビルドログに表示されます。

ビルドパラメーターを参照するには、その名前をパーセント記号で囲んで使用します(例: %teamcity.build.number%)。

パーセント記号TeamCityの間にあるテキストは、プロパティへの参照と見なされます。プロパティがビルド構成で見つからない場合、参照は暗黙的なエージェント要件となり、このようなビルド構成は、このプロパティが定義されているエージェントでのみ実行できます。エージェントで定義された値がビルドで使用されます。

TeamCityがパーセント記号のテキストをプロパティへの参照として処理しないようにするには、2つのパーセント記号を使用します。プロパティ参照がサポートされている値の %% はすべて、ビルドに値を渡す前に % に置き換えられます。例: %Y%m%d%H%M%S をビルドに渡す場合は、%%Y%%m%%d%%H%%M%%Sに変更します。

参照を使用できる場所

設定

説明

ランナー設定、アーティファクト仕様を構築する

ビルドに渡される任意のプロパティ

ユーザー定義のプロパティと環境変数

ビルドに渡される任意のプロパティ

ビルド番号の形式

事前定義されたサーバービルドプロパティのみ

VCSルートとチェックアウトルールの設定

ビルドに渡される任意のプロパティ

VCSラベルパターン

system.build.number および事前定義されたサーバービルドプロパティ

成果物の依存関係の設定

事前定義されたサーバービルドプロパティのみ

ビルド構成でビルドパラメーターを参照し、そこで定義されていない場合、構成のエージェント要件になります。ビルド構成は、このプロパティが定義されているエージェントでのみ実行されます。

パスワードフィールドにはパラメータへの参照も含めることができますが、この場合、参照はパスワード値としてマスクされているため表示できません。

依存関係からのパラメータの使用と上書きの詳細については、このセクションを参照してください。

VCSのラベリングパターンとビルド番号でのビルドパラメータの使用

ビルド番号パターンとVCSラベル付けパターンでは、%[env|system].property_name% 構文を使用して、サーバー側で既知のプロパティを参照できます。

  • サーバーと事前定義済みプロパティの参照

  • パラメーターページのビルド構成の設定で定義されたプロパティ

例:VCSリビジョン番号は %build.vcs.number%として指定できます。

ビルドスクリプトでのビルドパラメータの使用

env. プレフィックス(環境変数)で始まるすべてのビルドパラメーターは、ビルドのプロセス環境に渡されます(プレフィックスは省略されます)。

system. プレフィックス(システムプロパティ)で始まるすべてのビルドパラメーターは、サポートされているビルドスクリプトエンジンに渡されsystem. プレフィックスのないプロパティ名参照できます
この構文は(TeamCity設定ではなくビルドスクリプトで機能することに注意してください。

  • AntMaven、およびNAntの場合、${<property name>}を使用します。

  • MSビルド(Visual Studio 2005/2008プロジェクトファイル)の場合は、$(<property name>)を使用します。MSBuildはドット付きの名前(.)をサポートしていないため、ビルドスクリプト内でプロパティを使用する場合は、._ に置き換える必要があることに注意してください。

  • Gradleの場合、TeamCityシステムプロパティはGradleプロパティ( gradle.properties ファイルで定義されたものと同様)としてアクセスでき、次のように参照されます。

    • Groovy識別子として許可される名前(プロパティ名にはドットが含まれません):

    println "Custom user property value is $\{customUserProperty\}"
    • Groovy識別子として使用できない名前(プロパティ名にドットが含まれています): たとえば build.vcs.number.1): project.ext["build.vcs.number.1"]

TeamCityがビルドプロセスを開始すると、次の優先順位のビルドパラメータが使用されます(一番上のものがより高い優先順位を持ちます)。

  • プロジェクトレベルおよびエージェントレベルのビルドパラメーターファイルのパラメータ

  • 定義済みパラメーター

  • カスタムビルドを実行するダイアログで定義されたパラメーター

  • ビルド構成設定で定義されたパラメーター

  • プロジェクトで定義されたパラメーター (プロジェクトに定義されたパラメーターは、そのすべてのサブプロジェクトとビルド構成に継承されます。必要に応じて、ビルド構成で再定義できます)

  • テンプレートで定義されたパラメータ (もしあれば)

  • エージェントの buildAgent.properties ファイルで定義されたパラメーター

  • ビルドエージェントプロセス自体の環境変数

結果のパラメーターのセットは、ビルドスクリプトからアクセスできるファイルにも保存されます。詳細については、teamcity.build.properties.file システムプロパティまたは定義済みのビルドパラメータTEAMCITY_BUILD_PROPERTIES_FILE 環境変数の説明を参照してください。