カスタムパラメーターの作成とセットアップ

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

お名前の制限

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

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

TeamCity UI で

プロジェクトまたは構成設定に移動し、パラメータータブに切り替えます。パラメーターの優先順位と継承ルールについては、この記事を参照してください: パラメーター値。
入力パラメータータブに切り替えます。出力パラメーターはビルドチェーンでのみ使用されます。詳しくは、こちらの記事を参照してください: ビルドチェーンでパラメーターを使用する。
新しいパラメーターを追加ボタンをクリックしてください。
パラメーターの種類を指定し、パラメーター名を入力します。さまざまなパラメーター型の違いの詳細については、この記事を参照してください: ビルドパラメーターの構成。
必要な値の型オプションを選択します。これらのオプションは、パラメーターが持つことができる値を制御します。
- テキスト - パラメーターに任意の文字列値を持たせることができるデフォルトの型です。オプションで、許可値を表示の必須オプションを選択して、許可される値を特定の RegEx パターンに一致する値のみに制限したり、パラメーターが空にならないようにしたりすることができます。
- チェックボックス - 可能なパラメーター値の数を 2 つに制限します。カスタムビルドを実行するダイアログでチェックボックスとしてレンダリングされ、ユーザーはこれらの値を切り替えることができます。チェックされた状態とチェックされていない状態のデフォルト値は、それぞれ 真 と ヌル です。チェック時の値フィールドと未チェック時の値フィールドを使用して、カスタム値のペア (はい / いいえ、1/0、デバッグ / リリースなど) を設定できます。
- パスワード - "Text" 型と同様に、"Password" パラメーターは任意の文字列を値として受け付けることができます。ただし、この値がビルドの外部に Exposed されることはありません: TeamCity は、この機密値を UI、ビルドログ、DSL コード、REST API レスポンスペイロードから隠します。
  パスワードは、 TeamCity データディレクトリ以下の構成ファイルに保存されます。サーバーの暗号化設定に応じて、値はスクランブルされるか、カスタムキーで暗号化されます。
  パスワード値は、単純な検索と置換のアルゴリズムによってビルドログから隠されます。「123」などの単純なパスワードを使用している場合、「123」文字列のすべての出現がログで置き換えられ、パスワードが公開される可能性があります。
  また、パラメーターを「パスワード」型に設定しても、データの安全性が完全に保証されるわけではないことにも留意してください。プロジェクト管理者は誰でもパラメーターの生の値を取得でき、ビルドスクリプトを変更できる開発者は、パスワードを漏らす悪意のあるコードを書く可能性があります。
- 選択 - 定義済みの値のセットを指定できます。カスタムビルドを実行するダイアログを呼び出すユーザーは、複数選択を許可値に応じて、リストから 1 つまたは複数の値を選択できます。値は、TeamCity UI に表示されるオプションの値を付けて指定できます (例: Windows => win)。
- リモートシークレット — 値を手動で入力できないパラメーター。代わりに、実行中のビルドでこの値が必要になったときに、リモートストレージから値が安全に取得されます。詳細については、次の記事を参照してください: HashiCorp Vault 連携。
オプション: カスタムビルドを実行するユーザーに影響する追加オプションを指定するには、「カスタムビルドを実行」ダイアログの設定をカスタマイズをクリックします。
- 表示 - ユーザーがこのパラメーターを編集できるかどうか (または編集する必要があるかどうか) を指定します。
  - 通常のパラメーターは、カスタムビルドを実行するダイアログに表示されるデフォルトのパラメーターです。
  - 非表示のパラメーターは、カスタムビルドを実行するダイアログには表示されません。ユーザーに表示させたくないサービスパラメーターには、この型を使用します。シークレットパラメーターとは異なり、非表示のパラメーターの値をビルドログにエコーしたり、REST API 経由で要求したりすることが可能になります。
  - 確認パラメーターは、ユーザーが新しいビルドをトリガーするたびにカスタムビルドを実行するダイアログを呼び出して、実行ごとに有効な値が提供されるようにします。この型を使用して、カスタム確認ダイアログを実装することもできます (以下の例のセクションを参照)。
- 説明とラベルフィールドを使用すると、ユーザーが正しいパラメーター値を選択するのに役立つヒントを追加できます。
- 読み取り専用パラメーターは、カスタムビルドを実行するダイアログに無効なエディターを表示し、ユーザーがパラメーター値を変更できないようにします。値をロックするとともに、このパラメーターをユーザーから非表示にする場合は、表示オプションを非表示に設定します。
オプション: カスタムパラメーターにデフォルト値を設定する必要がある場合は、対応するフィールドにデフォルト値を入力します。最終パラメーター値を子プロジェクトまたは構成に設定する必要がある場合、ビルド中に計算する必要がある場合、このパラメーターの異なる値を別のエージェントに報告させる必要がある場合は、このフィールドを空のままにすることもできます。利用可能な値ソースの詳細については、記事パラメーター値を参照してください。

Kotlin DSL で

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

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 Vault 連携

トークン

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

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

スクランブル化されたシークレット

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

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

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

REST API の使用

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

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

   

リクエスト本体:

{
  "name" : "parameter.from.rest",
  "value" : "custom_value"
}

     

また、 /アプリ/rest/ビルドキュー エンドポイントにリクエストを送信して、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 に表示されず、ビルドプロセスに直接渡されます。

teamcity.default.properties という名前のテキストファイルを作成します。
system.<お名前>=<値> または env.<お名前>=<値> 形式のパラメーターを入力します。例: env.CATALINA_HOME=C:\tomcat_6.0.13
このファイルをターゲットリポジトリのルートディレクトリにプッシュします。
必要なチェックアウト設定をセットアップし、ファイルがビルド作業ディレクトリにチェックアウトされるようにします。

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

例

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

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

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 は新しいビルドの実行を許可しません。

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 つの値のみを選択できます。値は、カスタムビルドを実行するダイアログのコンボボックス項目として表示されます。

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>

     

複数選択パラメーター

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

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

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>

     

確認ダイアログ

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

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