TeamCity 2019.1ヘルプ

ビルドパラメータの設定

このページで:

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

ビルドパラメータの種類

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

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

  • 環境変数( env. プレフィックスを使用して定義されている)は、生成されたビルドプロセスにenvironmentとして渡されます。

  • システムプロパティー( `system。"プレフィックスを使用して定義されている)は、ビルドツール固有の変数としてサポートされているランナーのビルドスクリプト(たとえば、Ant、MSBuild)に渡されます。

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

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

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

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

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

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

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

どのテキスト設定でも、%parameter.name% の形式の文字列をビルド時の実際の値で置き換えるパラメータを参照できます。定義されていないパラメーターへの参照がある場合、暗黙のエージェント要件と見なされるため、ビルドは定義されたパラメーターを持つエージェントでのみ実行されます。

パラメータ名の制限

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

  • それは次の文字だけを含むべきです: [a-zA-Z0-9._-*]

  • ASCII文字で始まっているはずです

パラメータ名がこれらの要件を満たしていない場合、TeamCityはパラメータ編集ページに警告を表示します。

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

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

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

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

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

%[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設定では機能しません )。

  • AntMavenNAntには $(<property name>)を使用してください。

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

  • Gradleの場合:TeamCityシステムプロパティーはGradleプロパティーとしてアクセスでき( gradle.properties ファイルで定義されているものと同様)、次のように参照されます:
    a)Groovy識別子として許される名前(プロパティー名はドットを含みません):

    println "Custom user property value is $\{customUserProperty\}"

    b)Groovy識別子として使用できない名前(プロパティー名にドットが含まれている): たとえば build.vcs.number.1): project.ext["build.vcs.number.1"]

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

  • プロジェクトレベルとエージェントレベルのビルドパラメータファイルからのパラメーター。

  • 事前定義パラメーター。

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

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

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

  • テンプレートで定義されているパラメータ(ある場合)。

  • エージェントの buildAgent.properties ファイルに定義されているパラメーター。

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

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


関連事項:

管理者ガイド : プロジェクトレベルとエージェントレベルのビルドパラメータ | 定義済みのビルドパラメータ | エージェント要件の設定