TeamCity オンプレミス 2025.11 ヘルプ

カスタムパラメーターの作成と設定

このトピックでは、カスタム TeamCity パラメーターを作成し、その外観と動作を構成する方法について説明します。

名前の制限

構成パラメーターの名前には、[a-zA-Z0-9._-*] 文字のみが含まれ、ASCII 文字で始まる必要があります。

新しいパラメーターを作成する方法

TeamCity UI 内

  1. プロジェクトまたは構成設定に移動し、パラメータータブに切り替えます。パラメーターの優先順位と継承ルールについては、この記事を参照してください: パラメーター値。

  2. 入力パラメータータブに切り替えます。出力パラメーターはビルドチェーンでのみ使用されます。詳細については、この記事を参照してください: チェーンのビルドでパラメーターを使用します。

  3. 新規パラメーターを追加ボタンをクリックしてください。

    Create New Parameter

  4. パラメーターの種類を指定し、パラメーター名を入力します。さまざまなパラメーター型の違いの詳細については、この記事を参照してください: ビルドパラメーターの設定。

  5. 必要な値の型オプションを選択します。これらのオプションは、パラメーターが持つことができる値を制御します。

    • テキスト - パラメーターに任意の文字列値を持たせることができるデフォルトの型です。オプションで、許容値を表示の必須オプションを選択して、許可される値を特定の RegEx パターンに一致する値のみに制限したり、パラメーターが空にならないようにしたりすることができます。

    • チェックボックス - 可能なパラメーター値の数を 2 つに制限します。カスタムビルドを実行するダイアログでチェックボックスとしてレンダリングされ、ユーザーはこれらの値を切り替えることができます。チェックされた状態とチェックされていない状態のデフォルト値は、それぞれ true と null です。チェック値フィールドと未チェックの値フィールドを使用して、カスタム値のペア (はい / いいえ、1/0、デバッグ / リリースなど) を設定できます。

    • パスワード — 「テキスト」型と同様に、「パスワード」パラメーターは任意の文字列を値として受け入れることができます。ただし、この値はビルドの外部に公開されることはありません。TeamCity は、この機密値を UI、ビルドログ、DSL コード、REST API 応答ペイロードから非表示にします。

      パスワードは、TeamCity データディレクトリの構成ファイルに保存されます。サーバーの暗号化設定に応じて、値はスクランブルされるか、カスタムキーで暗号化されます。

    • 選択 - 定義済みの値のセットを指定できます。カスタムビルドを実行するダイアログを呼び出すユーザーは、複数選択を許可する値に応じて、リストから 1 つまたは複数の値を選択できます。値は、TeamCity UI に表示されるオプションの値 (たとえば、Windows => win) で指定できます。

    • リモートシークレット — 値を手動で入力できないパラメーター。代わりに、実行中のビルドでこの値が必要になったときに、リモートストレージから値が安全に取得されます。詳細については、次の記事を参照してください: HashiCorp ボールトの統合。

  6. オプション: カスタムビルドを実行するユーザーに影響する追加オプションを指定するには、「カスタムビルドの実行」ダイアログの設定をカスタマイズするをクリックします。

    • 表示 - ユーザーがこのパラメーターを編集できるかどうか (または編集する必要があるかどうか) を指定します。

      • 通常のパラメーターは、カスタムビルドを実行するダイアログに表示されるデフォルトのパラメーターです。

      • 非表示のパラメーターは、カスタムビルドを実行するダイアログには表示されません。ユーザーに表示させたくないサービスパラメーターには、この型を使用します。シークレットパラメーターとは異なり、非表示のパラメーターの値をビルドログにエコーしたり、REST API 経由で要求したりすることが可能になります。

      • プロンプトパラメーターは、ユーザーが新しいビルドをトリガーするたびにカスタムビルドを実行するダイアログを呼び出して、実行ごとに有効な値が提供されるようにします。この型を使用して、カスタム確認ダイアログを実装することもできます (以下の例のセクションを参照)。

    • 説明フィールドとラベルフィールドを使用すると、ユーザーが正しいパラメーター値を選択するのに役立つヒントを追加できます。

      Parameter Label and Description

    • 読み取り専用パラメーターは、カスタムビルドを実行するダイアログに無効なエディターを表示し、ユーザーがパラメーター値を変更できないようにします。値をロックするとともに、このパラメーターをユーザーから非表示にする場合は、表示オプションを非表示に設定します。

  7. オプション: カスタムパラメーターにデフォルト値を設定する必要がある場合は、対応するフィールドにデフォルト値を入力します。最終パラメーター値を子プロジェクトまたは構成に設定する必要がある場合、ビルド中に計算する必要がある場合、このパラメーターの異なる値を別のエージェントに報告させる必要がある場合は、このフィールドを空のままにすることもできます。利用可能な値ソースの詳細については、記事パラメーター値を参照してください。

Kotlin DSL

Kotlin DSL でカスタムパラメーターを定義するには、プロジェクトまたはビルド構成の params セクションに param("prefix.name", "value") 行を追加します。

import jetbrains.buildServer.configs.kotlin.* // Project-level Parameters project { params { param("env.ProjectLevelParam", "/System/DriverKit") param("ProjectLevelParam", "true") } } // Build Configuration-level Parameters object MyBuildConf : BuildType({ params { param("ConfigLevelParam", "24") param("env.ConfigLevelParam", "CTP") } })

ビルドステップから

##teamcity[setParameter name='ddd' value='fff'] サービスメッセージを送信してパラメーター値を更新するか、この名前のパラメーターがまだ存在しない場合は新しいパラメーターを作成します。

詳細については、この記事を参照してください: ビルドパラメーターの追加または変更。

シークレットを作成する

シークレットは機密データを保持するパラメーターであり、漏洩を防ぐために安全に保存する必要があります。シナリオと使用目的に応じて、次のオプションがあります。

パスワードパラメーター

特定の構成またはプロジェクト内でシークレット値を保存して使用する場合、TeamCity UI 内セクションに従って、パスワード型の通常の入力パラメーターを作成します。

リモートシークレット

値を保存する外部シークレットボールトがある場合は、リモートシークレット型のパラメーターを作成します。追加で構成されたボールト接続を使用すると、これらのパラメーターは要求に応じて安全に値を取得できます。

現在、HashiCorp Vault シークレットストレージのみがサポートされています。

詳細については次の記事を参照してください: HashiCorp ボールトの統合

トークン

プロジェクトがリモート VCS に設定を保存する場合、シークレット値を公開せずに設定する必要がある場合があります。これを行うには、シークレットを保存するサーバー側トークンを作成し、その名前をパラメーター値として渡します。

詳細についてはこのトピックを参照してください: トークンの管理

スクランブルされた秘密

バージョン設定を使用せずにトークンを作成することもできます。この場合、トークンはディスク (TeamCity データディレクトリ内) に保存されているプロジェクト構成ファイル内でのみ使用できます。

このようなトークンを作成するには、プロジェクトアクションメニューを呼び出して、安全な値をスクランブルします ... をクリックします。

Scramble value

ポップアップ表示されるダイアログで、秘密の値を入力し、「スクランブル」をクリックします。ダイアログを閉じる前に、スクランブルされた値をコピーすることを忘れないでください。

REST API の使用

TeamCity REST API 経由でパラメーターを作成するには、POST リクエストを必要なエンドポイントに送信し、リクエスト本文としてプロパティを渡します。

POST <SERVER_URL>/app/rest/projects/MyProject/parameters # or POST <SERVER_URL>/app/rest/buildTypes/MyProject_MyConfig/parameters

リクエスト本体:

<property name="parameter.from.rest" value="custom_value"/>
{ "name" : "parameter.from.rest", "value" : "custom_value" }

また、/app/rest/buildQueue エンドポイントにリクエストを送信して、1 回のビルド実行のみに使用できる 1 回限りのパラメーターを作成することもできます。次のリクエストは、新しいパスワードパラメーターを使用して新しいビルドを開始します。

/app/rest/buildQueue
<build> <buildType id="MyBuildConfID"/> <properties> <property name="env.password" value="mySecret"> <type rawValue="password"/> </property> </properties> </build>
{ "buildType": { "id": "MyBuildConfID" }, "properties": { "property": [{ "name": "env.password", "value": "mySecret", "type": { "rawValue": "password" } }] } }

REST API を介したパラメーター管理の詳細については、この記事を参照してください: 型付きパラメーターの管理。

デフォルトのプロパティファイル内

このメソッドを使用すると、同じ VCS ルートを共有するビルド構成でのみ使用できるパラメーターを宣言できます。この方法で定義されたパラメーターは TeamCity UI には表示されず、ビルドプロセスに直接渡されます。

  1. teamcity.default.properties という名前のテキストファイルを作成します。

  2. system.<name>=<value> または env.<name>=<value> 形式のパラメーターを入力します。例: env.CATALINA_HOME=C:\tomcat_6.0.13

  3. このファイルをターゲットリポジトリのルートディレクトリにプッシュします。

  4. 必要なチェックアウト設定をセットアップし、ファイルが作業ディレクトリを構築するにチェックアウトされるようにします。

ビルド構成の teamcity.default.properties パラメーターを使用して、プロパティファイルの名前とパスを変更できます。

サンプル

チェックボックスパラメーター

このパラメーターは、カスタムビルドを実行するダイアログにチェックボックスを表示します。パラメーターは、release (チェックあり) と debug (チェックなし) の値を切り替えることができます。

Checkbox parameter
Checkbox parameter settings
object Test : BuildType({ name = "Test" params { checkbox("CheckBoxDefaultParam", "debug", // Initial value label = "Release configuration", description = """Check to run the build in "Release" configuration. Otherwise, the "Debug" configuration is used.""", display = ParameterDisplay.PROMPT, checked = "release", unchecked = "debug") } })

JSON ペイロード:

{ "name": "CheckBoxDefaultParam", "value": "debug", "type": { "rawValue": "checkbox description='Check to run the build in \"Release\" configuration. Otherwise, the \"Debug\" configuration is used.' label='Release configuration' uncheckedValue='debug' checkedValue='release' display='prompt'" } }

XML ペイロード:

<property name="CheckBoxDefaultParam" value="debug"> <type rawValue="checkbox description='Check to run the build in &quot;Release&quot; configuration. Otherwise, the &quot;Debug&quot; configuration is used.' label='Release configuration' uncheckedValue='debug' checkedValue='release' display='prompt'"/> </property>

正規表現パラメーター

このパラメーターは、指定された正規表現に一致する文字列値のみを受け入れます。無効な値が入力された場合、TeamCity では新しいビルドの実行は許可されません。

RegEx Parameter
RegEx parameter settings
object MyBuildConfig : BuildType({ params { text("EmailRegExParam", "johndoe@jetbrains.com", regex = """^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}${'$'}""", validationMessage = "Invalid email address") } })

JSON ペイロード:

{ "name": "EmailRegExParam", "value": "johndoe@jetbrains.com", "type": { "rawValue": "text regexp='^|[\\w-\\.|]+@(|[\\w-|]+\\.)+|[\\w-|]{2,4}$' validationMode='regex' validationMessage='Invalid email address' display='normal'" } }

XML ペイロード:

<property name="EmailRegExParam" value="johndoe@jetbrains.com"> <type rawValue="text regexp='^|[\w-\.|]+@(|[\w-|]+\.)+|[\w-|]{2,4}$' validationMode='regex' validationMessage='Invalid email address' display='normal'"/> </property>

単一選択パラメーター

このパラメーターは複数の値を定義しますが、ユーザーは一度に 1 つの値のみを選択できます。値は、カスタムビルドを実行するダイアログのコンボボックス項目として表示されます。

Single selection parameter 1
Single selection parameter 2
Single select parameter settings
object MyBuildConf : BuildType({ params { select("SingleSelectParam", "linux", options = listOf( "Windows" to "win", "Linux" to "linux", "macOS" to "mac" ) ) } })

JSON ペイロード:

{ "name": "SingleSelectParam", "value": "linux", "type": { "rawValue": "select data_5='mac' label_5='macOS' label_3='Linux' display='normal' data_1='win' label_1='Windows' data_3='linux'" } }

XML ペイロード:

<property name="SingleSelectParam" value="linux"> <type rawValue="select data_5='mac' label_5='macOS' label_3='Linux' display='normal' data_1='win' label_1='Windows' data_3='linux'"/> </property>

複数選択パラメーター

このパラメーターを使用すると、ユーザーは定義済みのリストから複数の値を選択できます。

Multiselect parameter

複数の項目を選択した場合、パラメーターは指定された区切り文字を使用してそれらの値を結合します。例: 区切り文字がデフォルトのコンマ (,) から縦棒 (|) に変更された場合、パラメーター値は 2023.03|2023.11|2024.03 のようになります。

Multiselect parameter UI settings
object Test : BuildType({ name = "Test" params { select("MultiSelectParam", "2023.03", allowMultiple = true, valueSeparator = "|", options = listOf( "master" to "2023.03", "2023.05", "2023.11", "2024.03", "2024.06")) } })

JSON ペイロード:

{ "name": "MultiSelectParam", "value": "2023.03", "type": { "rawValue": "select data_6='2024.06' data_5='2024.03' display='normal' multiple='true' valueSeparator='||' data_1='2023.03' label_1='master' data_4='2023.11' data_3='2023.05'" } }

XML ペイロード:

<property name="MultiSelectParam" value="2023.03"> <type rawValue="select data_6='2024.06' data_5='2024.03' display='normal' multiple='true' valueSeparator='||' data_1='2023.03' label_1='master' data_4='2023.11' data_3='2023.05'"/> </property>

確認ダイアログ

構成にプロンプト型のパラメーターがある場合、ユーザーが新しいビルドを実行しようとするたびに、カスタムビルドを実行するダイアログがポップアップ表示されます。ビルドは、ユーザーがこのパラメーターに有効な値を入力した後にのみ開始されます。この動作を使用して、構成が過度に実行されるのを防ぐカスタム確認ダイアログを実装できます。

Starting Prompt
Prompt dialog settings
object Test : BuildType({ name = "Test" params { text("PromptConfirmation", "", label = "Deployment build confirmation", description = "This configuration triggers the deployment chain, which uploads updated NuGet packages and Docker images to public sources. Do you want to continue?", display = ParameterDisplay.PROMPT, regex = "deploy", validationMessage = """Type "deploy" to run this build""") } })

JSON ペイロード:

{ "name": "PromptConfirmation", "value": "", "type": { "rawValue": "text regexp='deploy' validationMessage='Type \"deploy\" to run this build' display='prompt' description='This configuration triggers the deployment chain, which uploads updated NuGet packages and Docker images to public sources. Do you want to continue?' label='Deployment build confirmation' validationMode='regex'" } }

XML ペイロード:

<property name="PromptConfirmation" value=""> <type rawValue="text regexp='deploy' validationMessage='Type &quot;deploy&quot; to run this build' display='prompt' description='This configuration triggers the deployment chain, which uploads updated NuGet packages and Docker images to public sources. Do you want to continue?' label='Deployment build confirmation' validationMode='regex'"/> </property>
2026 年 3 月 08 日
ビルドパラメーターの設定 事前定義されたビルドパラメーターのリスト

関連ページ：

プロジェクト管理者ガイド

このセクションでは、プロジェクト管理に焦点を当てます。TeamCity プロジェクトとビルド構成の作成、ビルドステップの設定、依存関係チェーンの構成などについて説明します。基本的な TeamCity ワークフロー：次のダイアグラムは、基本的な TeamCity ワークフローを示しています。TeamCity サーバーはリポジトリの変更を検出しました。サーバーはこの変更をデータベースに書き込みます。ビルド構成に添付されたトリガーは、データベース内の関連する変更を検出し、ビルドを開始します。トリガー...

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

パラメーターは、TeamCity 設定およびビルドスクリプトの構文を介して参照するペアです。パラメーター部分は、生の値 () にすることも、別のパラメーターへの参照 () を含めることもできます。パラメーター型：TeamCity は次の 3 種類のパラメーターをサポートします。構成パラメーター — ビルド構成内で設定を共有することを主な目的とするパラメーター。これらのパラメーターを使用して、テンプレートから作成された構成やレシピを使用する構成をカスタマイズすることもできます。TeamCity は...

ビルドチェーン

ビルドチェーンは、スナップショット依存関係によって相互接続された一連のビルドです。ビルドチェーンは「パイプライン」と呼ばれることもあります。リビジョン同期が有効になっているスナップショット依存関係にリンクされたビルドチェーンの各部分は、ソースの同じスナップショットを使用します。一般的なユースケース：ビルドチェーンを指定する最も一般的な使用例は、プロジェクトの同じテストスイートを異なるプラットフォームで実行することです。例: リリースビルドの前に、さまざまなプラットフォームと環境でテストが正しく実...

チェーンのビルドでパラメーターを使用する

このトピックでは、TeamCity ビルドパラメーターを使用して、ビルドチェーンの構成間で単純なデータを交換する方法を説明します。入力および出力パラメーター：ビルド構成設定のパラメーターページでは、入力パラメーターと出力パラメーターを切り替えることができます。どちらも手動で作成された名前と値のペアです。主な違いは、意図された使用例とアクセシビリティ設定にあります。入力パラメーター入力パラメーターは、定義する同じ構成で使用されるように設計されています。例: デフォルトのブランチ名を格納し、VCS...

カスタムビルドの実行

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

TeamCity データディレクトリ

TeamCity データディレクトリは、TeamCity サーバーが構成、ビルド結果、現在の操作ファイルを保存するために使用するファイルシステム上のディレクトリです。このディレクトリは、すべての構成設定の 1 次ストレージであり、TeamCity のインストールに不可欠なデータを保持します。ビルド履歴、ユーザーとそのデータ、その他のデータはデータベースに保存されます。ディレクトリとデータベースに保存されるデータの説明については、バックアップに関する注意事項を参照してください。このドキュメントや他...