ビルドパラメーターの構成

パラメーターは、TeamCity 設定とビルドスクリプトで %\パラメーター名% 構文を使用して参照する お名前=値 ペアです。

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

パラメーターの種類

TeamCity は 3 種類のパラメーターをサポートしています:

構成パラメーター — ビルド構成内で設定を共有することを主な目的とするパラメーター。これらのパラメーターを使用して、テンプレートから作成された構成やレシピを使用する構成をカスタマイズすることもできます。 TeamCity は、このタイプのパラメーターをビルドプロセスに渡しません (つまり、これらのパラメーターはビルドスクリプトエンジンからアクセスできません)。
環境変数 — 環境。 接頭辞で始まるパラメーター。これらのパラメーターは、システムのデフォルトの環境変数と同様に、ビルドランナーのプロセスに渡されます。
システムプロパティ — system. 接頭辞で始まるパラメーター。 TeamCity は、この種類のパラメーターを、特定のランナーの構成ファイルにビルドツール固有の変数として渡すことができます。

主なユースケース

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

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

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

   

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

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

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

   

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

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 つのステップとブール値の スキップ.任意.ステップ パラメーターがあります。ステップ #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 を実行する必要がないコピーでは、 スキップ.任意.ステップ パラメーターをオーバーライドして 真 に設定します。

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%"""
        }
    }
})

   

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

エージェントの要件を使用すると、 パラメーター-演算子-値 条件を指定できます。これらの条件を満たすエージェントのみが、このビルド構成を構築できます。

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

すべてのエージェントで使用できる事前定義された構成パラメーター (たとえば、 teamcity.agent.name)。
エージェントによって報告される環境変数 (たとえば、 env.DOTNET_SDK_バージョン)。
エージェントの buildAgent.properties ファイルに存在するカスタム構成パラメーター (たとえば、TeamCity UI で カスタム.エージェント.パラメーター を作成し、エージェントのプロパティファイルに カスタム.エージェント.パラメーター=MyValue 行を追加します)。

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

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 では、 $(<パラメーター_お名前>) 構文を使用してパラメーター値を渡します。

次のサンプル .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.空き容量 MB パラメーターは、この特定のビルドエージェントの合計空き容量を報告し、 DotNetCLI_Path パラメーターは .NET CLI インストールパスを返します。

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

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

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

詳細については、カスタムパラメーターの作成とセットアップと暗黙の要件を参照してください。

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

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

# An agent's "buildAgent.properties" files

######################################
#   Default Build Properties         #
######################################
# ...
agent.tier=Platinum
# ...

    

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

object Build : BuildType({
    name = "My build config"
    requirements {
        equals("agent.tier", "Platinum")
    }
})

    

カスタムビルドパラメーター

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

例: Maven ビルドステップの Java バージョンを指定しない場合、 JAVA_HOME 環境変数で定義されたエージェントのデフォルトの Java が使用されます。これを上書きするには、カスタムビルド実行ダイアログで env.JAVA_HOME 環境変数 パラメーターを追加し、 %env.JDK_21_0_ARM64% などの既存のエージェントパラメーターを設定します。

動的に作成されたカスタムパラメーター

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

パラメーター値

TeamCity パラメーターは、以下に示す 1 つまたは複数のソースから値を取得できます。

強制設定テンプレートとして選択されたテンプレートの値。これらの値は、ユーザーが無効にしたり上書きしたりすることはできません。
カスタムビルドを実行するダイアログのパラメータータブ。
ビルド構成またはパイプライン設定のパラメーターに割り当てられたカスタム値。
パラメーターの親プロジェクト設定に割り当てられたカスタム値。プロジェクト内で定義されたパラメーターは、そのすべての子エンティティに継承されます。
通常のビルド構成テンプレートで指定された値。
ビルドエージェントの構成ファイル (<エージェントホーム>/設定/ビルドエージェント.プロパティ ファイル) で指定された値。
エージェントが TeamCity サーバーに接続するときに報告する値。これらの値は、エージェント環境を記述するパラメーターに渡されます。例: この特定のエージェント上の .NET 7 SDK へのパスを保存する DotNetCoreSDK7.0_パス パラメーター。
事前定義されたビルドパラメーターの値。これらのパラメーターは、特定のビルドのスコープ内のサーバー側で値を収集することも (ビルド.番号 パラメーターなど)、ビルドの開始直前にエージェント側で値を収集することもできます (teamcity.agent.work.dir.空き容量 MB パラメーターなど)。

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

ビルド中にパラメーター値をオーバーライドする

初期パラメーター値は、 ##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 Vault 連携。

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

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

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

/アプリ/rest/ビルド/{buildLocator}?フィールド=元のプロパティ(*) — ビルド構成からのユーザー定義パラメーターとそのデフォルト値を返します。
/アプリ/rest/ビルド/{buildLocator}?フィールド=開始プロパティ(*) — エージェントによって報告されたすべてのパラメーターと、ビルドの開始時にその値を返します。
/アプリ/rest/ビルド/{buildLocator}?フィールド=結果プロパティ(*) — ビルドが完了するまでにエージェントによって報告されたすべてのパラメーターとその値を返します。

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

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 年 9 月 11 日