TeamCity オンプレミス 2025.11 ヘルプ

ビルドパラメーターの設定

パラメーターは、TeamCity 設定およびビルドスクリプトの %parameterName% 構文を介して参照する name=value ペアです。

パラメーター value 部分は、生の値 (release.number=2026.1) にすることも、別のパラメーターへの参照 (system.tomcat.libs=%env.CATALINA_HOME%/lib/*.jar) を含めることもできます。

パラメーター型

TeamCity は次の 3 種類のパラメーターをサポートします。

  • 構成パラメーター — ビルド構成内で設定を共有することを主な目的とするパラメーター。これらのパラメーターを使用して、テンプレートから作成された構成やレシピを使用する構成をカスタマイズすることもできます。TeamCity は、この型のパラメーターをビルドプロセスに渡しません (つまり、これらのパラメーターはビルドスクリプトエンジンからアクセスできません)。

  • 環境変数 — env. 接頭辞で始まるパラメーター。これらのパラメーターは、システムのデフォルトの環境変数と同様に、ビルドランナーのプロセスに渡されます。

  • システムプロパティ — system. 接頭辞で始まるパラメーター。TeamCity は、この型のパラメーターをビルドツール固有の変数として特定のランナーの設定ファイルに渡すことができます。

主な使用例

ビルドスクリプトをパラメーター化する

時々カスタムスクリプトのバリエーションを実行する必要がある場合は、生の値をパラメーターに置き換えることができます。例: 次の Kotlin DSL サンプルは、デフォルトで clean build コマンドを実行する Gradle ステップを示しています。

object GradleStepParameters : BuildType({ params { param("gradle.task", "clean build") } steps { gradle { id = "gradle_runner" // runs "clean build" by default tasks = "%gradle.task%" } } })

ユーザーはカスタムビルドをトリガーしてこのパラメーターをオーバーライドし、別の Gradle タスクを実行できます。

Override build parameter

このパラメーターには、サポートされている値を事前に入力しておくこともできます。そうすれば、ユーザーは入力する代わりに、コンボボックスからオプションを選択できるようになります。

Select build parameter
params { select("gradle.task", "clean build", options = listOf("clean build", "test build", "build assemble")) }

... またはチェックボックス。

Check build parameter values
params { select("gradle.task", "clean build", allowMultiple = true, valueSeparator = "%space.separator%", options = listOf("clean", "test", "build", "assemble", "package")) param("space.separator", " ") }

パラメーターのカスタマイズの詳細については、カスタムパラメーターの作成と設定を参照してください。

    共通設定を共有する

    プロジェクト所有のパラメーターには、複数のビルド構成またはパイプラインに共通の設定を保存できます。例: 組織がすべてのリポジトリに対して厳格なブランチ命名ガイドラインに従っている場合は、各 VCS ルートに対して同一のブランチ仕様やその他の設定を入力することを回避できます。

    // Project level params { param("default.branch.spec", """ refs/heads/dev-* -:refs/heads/sandbox -:refs/heads/testing-* """.trimIndent()) param("default.branch", "refs/heads/dev-2024.1") } // VCS Root object GitHubRepoRoot : GitVcsRoot({ name = "My Root" url = "..." branch = "%default.branch%" branchSpec = "%default.branch.spec%" authMethod = password { userName = "..." password = "..." } })

      生の値を避ける

      TeamCity エージェントは、ツールのインストールパスを格納する複数のパラメーターを報告します。これらのパラメーターは、ビルドスクリプトや TeamCity 設定で使用できます。これにより、エージェントに依存しない条件を作成し、潜在的なエラーを最小限に抑えることができます。

      steps { gradle { name = "Gradle step" tasks = "build-dist" jdkHome = "%\env.JDK_19_0_ARM64%" } }

      場合によっては、このデータは機密情報であるため（たとえば、ビルドスクリプト内で使用される認証情報など）、生の値の使用を避けたい場合があります。これらの機密情報を TeamCity UI とビルドログの両方から非表示にするには、パスワードパラメーターを作成します。

        テンプレートとレシピをカスタマイズする

        テンプレートを使用すると、類似したビルド構成とパイプラインをすばやく作成できます。特定のテンプレート設定をパラメーター化することで、このテンプレートから派生する各オブジェクトに固有の動作を実装できます。

        例: 次のビルド構成には 2 つのステップとブール値の skip.optional.step パラメーターがあります。ステップ #2 は、このパラメーター値に応じて実行されるかどうかが決まります。

        import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.script object SourceConfig : BuildType({ name = "SourceConfig" params { param("skip.optional.step", "false") } steps { script { name = "Mandatory Step" scriptContent = """echo "Mandatory step #1 is running..."""" } script { name = "Optional Step" scriptContent = """echo "Optional step #2 is running..."""" conditions { equals("skip.optional.step", "false") } } }})

        この構成からテンプレートを抽出すると、同じ構成のコピーを複数作成できます。オプションのステップ #2 を実行する必要がないコピーでは、skip.optional.step パラメーターをオーバーライドして true に設定します。

        import jetbrains.buildServer.configs.kotlin.* object ConfigFromTemplate : BuildType({ templates(SourceConfigTemplate) name = "Build Config Based on Template" params { param("skip.optional.step", "true") } })

        レシピは、頻繁に使用されるアクションをカプセル化した汎用的なステップです。これらのオブジェクトは、パラメーターを使用して動作をカスタマイズすることもできます。

        <meta-runner name="cURL: File Download"> <description>A two-step recipe that utilizes the "curl -o %URL% %fileName%" command to download a file, and calls "ls" command to print the contents of a working directory afterwards</description> <settings> <parameters> <param name="URL" value="" spec="text description='The URL of a file to be downloaded' display='normal' label='Download URL:'"/> <param name="fileName" value="" spec="text description='Enter the saved file name or leave blank to keep the origin name' label='File name:'" /> <!--other parameters--> </parameters> <build-runners> <runner name="" type="simpleRunner"> <parameters> <param name="script.content" value="curl -o %URL% %fileName%" /> <param name="teamcity.step.mode" value="default" /> <param name="use.custom.script" value="true" /> </parameters> </runner> <runner name="" type="simpleRunner"> <parameters> <param name="script.content" value="ls" /> <param name="teamcity.step.mode" value="default" /> <param name="use.custom.script" value="true" /> </parameters> </runner> </build-runners> <requirements /> </settings> </meta-runner>

          ステップ実行条件を指定する

          ステップの実行条件を定義して、個々のステップを実行するかどうかを指定できます。これらの条件は、カスタムおよび事前定義された構成パラメーターと環境変数を使用して作成できます。

          例: ビルドエージェントのオペレーティングシステムに応じて、異なるシェルスクリプトを実行できます。

          import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.powerShell import jetbrains.buildServer.configs.kotlin.buildSteps.script object StepExecutionConditions : BuildType({ params { param("win.destination.path", "C:/Sources") param("unix.destination.path", "/Users/Admin/Sources") } steps { // PowerShell script runs only on Windows agents powerShell { name = "Copy File (Windows)" conditions { startsWith("teamcity.agent.jvm.os.name", "Windows") } scriptMode = script { content = """ Copy-Item "%system.teamcity.build.workingDir%/result.xml" -Destination %win.destination.path%""" } } // Command Line runner for non-Windows agents script { name = "Copy File (Unix)" executionMode = BuildStep.ExecutionMode.RUN_ON_FAILURE conditions { doesNotContain("teamcity.agent.jvm.os.name", "Windows") } scriptContent = """ cp "%system.teamcity.build.workingDir%/result.xml" %unix.destination.path%""" } } })

            エージェントの要件を指定する

            エージェントの要件を使用すると、parameter-operator-value 条件を指定できます。これらの条件を満たすエージェントのみが、このビルド構成を構築できます。

            エージェントの要件は、ビルドの開始前にエージェントがレポートできる値を持つパラメーターのみを使用して定義できます。これらのパラメーターは次のとおりです。

            • すべてのエージェントで使用できる事前定義された構成パラメーター (たとえば、teamcity.agent.name)。

            • エージェントによって報告される環境変数 (たとえば、env.DOTNET_SDK_VERSION)。

            • エージェントの buildAgent.properties ファイルに存在するカスタム構成パラメーター (たとえば、TeamCity UI で custom.agent.parameter を作成し、エージェントのプロパティファイルに custom.agent.parameter=MyValue 行を追加します)。

            Kotlin DSL では、 requirements コレクションを使用して新しい要件を定義します。

            object MyBuildConfig : BuildType({ requirements { // Only agents with .NET SDK 5.0 exists("DotNetCoreSDK5.0_Path") // Only Windows agents startsWith("teamcity.agent.jvm.os.name", "Windows") // Only agents with "Android" workload for .NET 7 SDK contains("DotNetWorkloads_7.0", "android") } })

              ビルダー構成をパラメーター化する

              .NET、Maven、Gradle、Ant および NAnt ランナーを使用すると、ビルド構成ファイルで TeamCity パラメーターを参照できます。この手法を使用すると、必要な値をビルドプロセスに渡すことができます。

              .NET では、$(<parameter_name>) 構文を使用してパラメーター値を渡します。

              次のサンプル .csproj ファイルは、2 つのカスタム MSBuild ターゲットを定義します。

              <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <PropertyGroup> <OutputZipFile>project.zip</OutputZipFile> <OutputUnzipDir>unzipped</OutputUnzipDir> </PropertyGroup> <Target Name="Zip"> <ItemGroup> <FilesToZip Include="project.proj*" /> </ItemGroup> <Exec Command="dir" /> <Microsoft.Build.Tasks.Message Text="##teamcity[progressMessage 'Archiving files to $(OutputZipFile) file...']"/> <Exec Command="PowerShell -command Compress-Archive @(FilesToZip, ',') $(OutputZipFile) -Force" /> </Target> <Target Name="Unzip"> <Microsoft.Build.Tasks.Message Text="##teamcity[progressMessage 'Unzipping files to $(OutputUnzipDir) folder...']"/> <Exec Command="PowerShell -command Expand-Archive $(OutputZipFile) -DestinationPath $(OutputUnzipDir) -Force" /> </Target> </Project>

              Maven および Ant のパラメーター値を参照するには、${parameterName} 構文を使用します。

              <configuration> <tasks> <property environment="env"/> <echo message="TEMP = ${env.TEMP}"/> <echo message="TMP = ${env.TMP}"/> <echo message="java.io.tmpdir = ${java.io.tmpdir}"/> <echo message="build.number = ${build.number}"/> </tasks> </configuration>

              Maven および Ant のパラメーター値を参照するには、${parameterName} 構文を使用します。

              <target name="buildmain"> <ant dir="${teamcity.build.checkoutDir}" antfile="${teamcity.build.checkoutDir}/build-test.xml" target="masterbuild_main"/> </target>

              Gradle ランナーの場合、TeamCity システムプロパティはネイティブ Gradle プロパティ (gradle.properties ファイルで定義されているプロパティ) としてアクセスできます。プロパティ名が Groovy 識別子として許可される場合 (ドットは含まれない)、次の構文を使用します。

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

              それ以外の場合、プロパティの名前にドットが含まれている場合 ( build.vcs.number.1 など)、代わりに project.ext["build.vcs.number.1"] 構文を使用します。

                パラメーターソース

                TeamCity のすべてのパラメーターは、定義済みパラメーターとカスタムパラメーター（TeamCity ユーザーが作成）の 2 つの主要なグループに分類できます。カスタムパラメーターは、個々のプロジェクト、ビルド構成、エージェントマシンなど、複数のレベルで宣言できます。

                定義済みのパラメーター

                TeamCity は、ビルドワークフローで参照できる複数の定義済みパラメーターを公開します。例: teamcity.agent.work.dir.freeSpaceMb パラメーターは、この特定のビルドエージェントの合計空き容量を報告し、DotNetCLI_Path パラメーターは .NET CLI インストールパスを返します。

                詳細については、この記事を参照してください: 事前定義されたビルドパラメーターのリスト。

                カスタムテンプレート、プロジェクト、構成、パイプラインパラメーター

                これらのパラメーターは、プロジェクト、構成、パイプライン設定内でユーザーによって作成されます。場合によっては、TeamCity が自動的に作成します。たとえば、CLI ステップが echo %MyParam% コマンドを実行するものの、MyParam が存在しない場合、すべてのビルドは失敗します。TeamCity はこれを設定ミスと認識し、この不足しているパラメーターの値が指定されない限り、新規ビルドを実行しません。つまり、不足しているパラメーターの存在は、新規ビルドの暗黙的な要件となります。

                詳細については、カスタムパラメーターの作成と設定および暗黙の要件を参照してください。

                カスタムエージェントパラメーター

                エージェント構成ファイル (<AGENT_HOME>/conf/buildAgent.properties) 内でパラメーターを手動で宣言できます。例: 次のサンプルは、カスタムビルドエージェントのランキングシステムを実装する方法を示しています。

                # An agent's "buildAgent.properties" files ###################################### # Default Build Properties # ###################################### # ... agent.tier=Platinum # ...

                このカスタムエージェントランクは、エージェント要件で使用できます。

                object Build : BuildType({ name = "My build config" requirements { equals("agent.tier", "Platinum") } })
                カスタムビルドパラメーター

                カスタムビルドをトリガーするユーザーは、既存のパラメーター値を上書きし、対応するダイアログタブで新しいパラメーターを追加できます。

                Add new parameters in custom run dialog
                動的に作成されたカスタムパラメーター

                既存のパラメーターを更新したり、新しいパラメーターを追加したりするには、##teamcity[setParameter name='foo' value='bar'] サービスメッセージをビルドログに出力します。

                パラメーター値

                TeamCity パラメーターは、以下にリストされている 1 つまたは複数のソースから値を取得できます。

                • 強制設定テンプレートとして選択されたテンプレートの値。これらの値は、ユーザーが無効にしたり上書きしたりすることはできません。

                • カスタムビルドを実行するダイアログのパラメータータブ。

                • ビルド構成またはパイプライン設定のパラメーターに割り当てられたカスタム値。

                • パラメーターの親プロジェクト設定に割り当てられたカスタム値。プロジェクト内で定義されたパラメーターは、そのすべての子エンティティに継承されます。

                • 通常のビルド構成テンプレートで指定された値。

                • ビルドエージェントの構成ファイル (<AGENT_HOME>/conf/buildAgent.properties ファイル) で指定された値。

                • エージェントが TeamCity サーバーに接続するときにレポートされる値。これらの値は、エージェント環境を記述するパラメーターに渡されます。例: この特定のエージェント上の .NET 7 SDK へのパスを保存する DotNetCoreSDK7.0_Path パラメーター。

                • 事前定義されたビルドパラメーターの値。これらのパラメーターは、特定のビルドのスコープ内のサーバー側で値を収集することも (build.number パラメーターなど)、ビルドの開始直前にエージェント側で値を収集することもできます (teamcity.agent.work.dir.freeSpaceMb パラメーターなど)。

                上記のリストでは、パラメーター値のソースも優先度の高いものから低いものの順に並べられています。つまり、同じパラメーターが異なるソースから異なる値を取得する場合、このリストの最も上位のソースの値が適用されます。例: my.parameter がエージェント設定ファイルとビルド設定の両方で定義されている場合、設定ページの値が優先されます。

                ビルド中にパラメーター値を上書きする

                初期パラメーター値は、##teamcity[setParameter name='foo' value='bar'] サービスメッセージを送信することで上書きできます。この方法で変更されたパラメーター値は、現在のビルドまたはビルドチェーンの範囲内でのみ更新されることに注意してください。パラメーター値を永続的に上書きするには、ビルドステップから以下に示すような REST API リクエストを送信してください。

                import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.script object UpdateBuildVersion : BuildType({ name = "Update Build Version" steps { script { id = "simpleRunner" scriptContent = """ version=%\build.version% ((version=version+1)) curl --location --request PUT 'http://<server_URL>/app/rest/projects/<project_name>/parameters/build.version' \ --header 'Accept: */*' \ --header 'Content-Type: text/plain' \ --header 'Authorization: Bearer your_token' \ --data ${'$'}version """.trimIndent() } } })

                リモートソースからパラメーター値を取得する

                TeamCity UI とビルドログの両方から機密データ（ログイン認証情報やアクセストークンなど）を隠すには、値をマスクするパスワードパラメーターを使用します。重要な値をさらに保護するには、それらの値をサードパーティ製の Vault に保存し、リモートシークレット型の TeamCity パラメーターを作成します。これらのパラメーターには明示的な「値」部分はありません。代わりに、TeamCity がパラメーター参照を解決する必要があるたびに実行するクエリが格納されます。

                現在、リモートシークレットストレージとしてサポートされているのは HashiCorp Vault のみです。詳細については、こちらの記事を参照してください: HashiCorp ボールトの統合。

                パラメーター値を追跡する

                ビルドが完了すると、ビルド結果ページのパラメータータブで、このビルド中に使用されたすべてのパラメーターを確認できます。TeamCity では、新しいパラメーターとビルド中に値が変更されたパラメーターがハイライトされます。

                Build parameters report

                REST API 経由で特定のビルドの初期パラメーター値と実際のパラメーター値を確認するには、/app/rest/builds/[{buildLocator}](https://www.jetbrains.com/help/teamcity/rest/buildlocator.html) エンドポイントに GET リクエストを送信し、スキーマの構築に従って必要なペイロードフィールドを指定します。

                • /app/rest/builds/{buildLocator}?fields=originalProperties(*) — ビルド構成からのユーザー定義パラメーターとそのデフォルト値を返します。

                • /app/rest/builds/{buildLocator}?fields=startProperties(*) — エージェントによって報告されたすべてのパラメーターと、ビルドの開始時にその値を返します。

                • /app/rest/builds/{buildLocator}?fields=resultingProperties(*) — ビルドが完了するまでにエージェントによって報告されたすべてのパラメーターとその値を返します。

                特定のパラメーターの初期値と最閉じを確認することもできます。これを行うには、対象パラメーターの名前を指定します。

                curl -L \ https:<SERVER_URL>/app/rest/builds/<BUILD_LOCATOR>?fields=\ originalProperties($locator(name:(value:(myParam),matchType:matches)),property),\ startProperties($locator(name:(value:(myParam),matchType:matches)),property),\ resultingProperties($locator(name:(value:(myParam),matchType:matches)),property)
                2026 年 3 月 09 日
                エージェントからビルドを切り離す カスタムパラメーターの作成と設定

                関連ページ：

                エージェント要件の設定

                エージェントの要件は、ビルド構成を実行できるエージェントを指定する条件です。現在存在するすべての要件を表示して新しい要件を作成し、特定の構成を実行できるエージェントを確認するには、ビルド設定 | エージェント要件にアクセスしてください。エージェント要件ビデオガイド：要件構文：エージェント要件は式です。ここは、定義済みまたはカスタム (ユーザー定義) のビルドパラメーターです。例: エージェントにインストールされているオペレーティングシステムを報告するパラメーター。要件では、エージェントがこの特...

                ビルド構成テンプレート

                構成テンプレートを作成するを使用すると、ビルド構成設定の重複を排除できます。類似した (必ずしも同一ではない) ビルド構成が複数あり、各構成を編集せずに 1 か所で共通設定を変更できるようにするには、それらの設定を含むビルド構成テンプレートを作成します。テンプレート設定を変更すると、このテンプレートに関連付けられているすべてのビルド構成に影響します。プロジェクトとそのサブプロジェクト内のすべてのビルド構成に対して、プロジェクト内のデフォルトテンプレートを定義することができます。詳細については、以...

                レシピの操作

                レシピは、1 つまたは複数の標準 TeamCity ステップに基づいたカスタムビルドステップです。TeamCity の組み込みステップに必要なオプションがなく、頻繁にエミュレートする場合 (たとえば、CLI ステップを使用してクラウドプロバイダー API 経由でアーティファクトをアップロードする場合)、このカスタムステップを再利用可能なレシピとして保存できます。レシピを作成することは、カスタムビルドステップを実装する TeamCity プラグインを開発するよりも簡単な代替手段です。重要なポイント...

                Kotlin DSL

                TeamCity では、バージョン管理で設定を XML 形式で保存するだけでなく、DSL (Kotlin 言語に基づく) で設定を保存することもできます。バージョン管理に保存された DSL を使用すると、プログラムで設定を定義できます。Kotlin は静的に型指定されるため、IDE で自動補完機能を自動的に受け取ります。これにより、利用可能な API オプションの発見がはるかに簡単になります。TeamCity での Kotlin DSL の使用に関するブログ投稿シリーズと推奨リファクタリングの記...

                Gradle

                このビルドステップは、Gradle プロジェクトのビルドに合わせて調整されており、およびを含むすべての Gradle ビルド構成をサポートします。前提条件：Gradle でビルドを実行するには、Gradle 0.9-rc-1 以降がすべてのエージェントマシンにインストールされている必要があります。あるいは、Gradle ラッパーを使用する場合は、バージョン管理にチェックインされた Gradle ラッパースクリプトを適切に構成する必要があります。ステップ設定：Gradle ステップ設定のリストと...

                カスタムビルドの実行

                通常、ビルド構成ではビルドトリガーを使用して、必要なスケジュールに従って、または TeamCity がソースコード内の新しい変更を検出したときに新しいビルドを開始します。これらの自動的にトリガーされるビルドに加えて、TeamCity ではビルドを手動で実行し、必要に応じて設定をカスタマイズすることもできます。つまり、新しいプロパティの追加または既存のプロパティの変更、特定の変更の選択、ビルドのスケジュール、ビルドを実行するエージェントの選択などを行うことができます。TeamCity には、カスタ...