レシピ YAML の構文

このドキュメントでは、 YAML レシピの一般的な構文について説明します。カスタム YAML レシピを作成するには、.yml 定義ファイルを作成して TeamCity にアップロードします (プロジェクト設定 | レシピ | プライベートレシピをアップロード)。

共通のレシピ構造

TeamCity YAML レシピの構造は次のとおりです：

name: myorg/recipe-name
title: The recipe title
version: 1.2.3
description: The recipe description
container: <container properties>
inputs: <input list>
steps: <step list>

  

お名前

必須:: はい
タイプ:: 文字列

一意のレシピ名。値は namespace/recipe-name フォーマットにする必要があります。ここで namespace はレシピ作成者が所有する JetBrains Marketplace の名前です。同じユーザーがアップロードしたすべてのレシピは、同一の名前空間を持つ必要があります。ユーザー名前空間の管理の詳細については、次の Marketplace ドキュメント記事を参照してください: TeamCity レシピのアップロード。

レシピ名と名前空間名は 5 – 30 文字で、英数字、ダッシュ、アンダースコアのみを使用する必要があります。ダッシュまたはアンダースコアで始まることや、連続したダッシュまたはアンダースコアを含めることはできません。

JetBrains マーケットプレイスにレシピをアップロードせず、プライベートレシピとしてのみ使用する場合は、 namespace の部分を省略できます。 recipe-name を単独で使用する場合、文字数制限は 100 文字（英数字、ダッシュ、アンダースコア）です。

タイトル

必須:: はい（マーケットプレイスにアップロードされたレシピのみ）
タイプ:: 文字列

TeamCity UI に表示される公開レシピ名 (ビルドステップの追加ページ、ビルドログなど)。

バージョン

必須:: はい（マーケットプレイスにアップロードされたレシピのみ）
タイプ:: 文字列

major.minor.patch 形式の数値レシピバージョン。 Minor および patch 部分は、プライベートレシピの場合はオプションですが、パブリックレシピの場合は必須です。

説明

必須:: はい
タイプ:: 文字列

レシピの公開説明。非公開レシピの場合は文字数制限なし、公開レシピの場合は最大 1000 文字まで。

container

必須:: いいえ
タイプ:: ContainerSettings オブジェクトまたは文字列

このレシピを実行する Docker または Podman コンテナーを指定するプロパティのセット。

inputs

必須: いいえ
タイプ: List<入力>

レシピを構成するときに TeamCity UI に表示される一連のエディター (テキストフィールド、チェックボックス、コンボボックスなど)。

steps

必須: はい
タイプ: List<ステップ>

ビルドの実行時にレシピによって実行されるビルドステップのリスト。

コンテナー設定

レシピ container フィールドの構文は次のとおりです。

container:
  image: alpine
  platform: linux
  parameters: -it

  

イメージ が唯一の必須フィールドである場合は、代わりにコンパクト形式を使用できます。

container: alpine

パブリック DockerHub イメージ名を指定しない限り、コンテナー内でレシピを実行するビルド構成には、レジストリにアクセスするための Docker レジストリ接続が必要です。

イメージ

必須:: はい
タイプ:: 文字列

コンテナーが生成される Docker/Podman イメージの名前。

platform

必須:: いいえ
タイプ:: 弦
サポートされている値: linux | windows

コンテナーイメージプラットフォームを指定します。

パラメーターを非推奨にする

必須:: いいえ
タイプ:: 文字列

追加のコンテナー実行パラメーターのリスト。

入力

入力はレシピステップで使用される変数であり、ユーザーがカスタマイズできます。スタンドアロンレシピをビルド構成に直接追加すると、入力の種類（テキスト入力の場合はテキストボックス、選択の場合はコンボボックスなど）に応じて UI エディターで設定できます。

レシピは uses フィールドを介して他のレシピを参照することもできます。その場合、入力値は TeamCity UI ではなく YAML で提供されます。

各入力の形式は次のとおりです。

<input-name>:
  type: text
  label: Main label
  description: Input description
  default: value1
  required: true

  

レシピ .yml ファイルでは、個々の入力定義は inputs ブロック内に配置されます。

inputs:
  - env.input_address:
      ...
  - env.input_subject:
      ...
  - env.input_message:
      ...

  

<入力名>

必須:: はい
タイプ:: 文字列

入力値を格納するビルドパラメーターの名前。生の値（フィールド名なし）として宣言されます。

入力名として、環境変数と通常のビルドパラメーターの両方を使用できます。

環境変数 (推奨)

環境。 接頭辞を使用して宣言されます。例: env.my-input。
ステップでは、パラメーター参照を使用せずに環境変数の値を取得できます。例: Bash スクリプトの INPUT_VAR="$my-input" 、Kotlin スクリプトの System.getenv("my-input") など。
ユーザーの資格情報やその他の機密データを要求する入力を除く、すべての入力に推奨されます。機密値は、すべての子プロセスやシステムツールに公開されてセキュリティ上の懸念が生じるため、環境変数に保存しないでください。

通常のビルドパラメーター

接頭辞なしで宣言されます。例: my-input
ステップは、値を取得するためにパラメーター参照を使用する必要があります（例: string myVal = "%my-input%";）。この構文は、入力値を装った悪意のあるコードを挿入するために悪用される可能性があります。そのため、通常のビルドパラメーターは、信頼できるユーザー入力にのみ使用することをお勧めします。

タイプ

必須:: はい
タイプ:: 弦
サポートされている値: テキスト | boolean | 選択 | パスワード

入力タイプ。この入力が取り得る値と、TeamCity UI の対応するエディターの外観と動作のオプションを指定します。

テキスト — デフォルトの入力タイプです。入力に任意の値を設定できます。レシピ設定にテキストボックスが表示されます。
boolean — 使用可能な入力値の数を真または偽に制限します。 TeamCity は、このタイプの入力に対してレシピ設定にチェックボックスを表示します。
選択 — ユーザーが選択できる値の固定範囲を指定できます。 TeamCity UI では、コンボボックスエディターとして表示されます。使用可能な値をリストする オプション フィールドを追加する必要があります。
inputs: - env.retry_timeout: type: select label: Retry timeout required: false default: 60 options: - 5 - 10 - 30 - 60
パスワード — テキスト に似ていますが、TeamCity UI とビルドログの両方で入力値をアスタリスクでマスクします。

ラベル

必須:: いいえ
タイプ:: 文字列

TeamCity UI のエディターの横に表示されるメイン入力ラベル。公開レシピの最大文字数は 100 文字です。

説明

必須:: いいえ
タイプ:: 文字列

TeamCity UI のエディターの下に表示される入力の説明。公開レシピの最大文字数は 250 文字です。

デフォルト

必須:: いいえ
タイプ:: 文字列

初期 / デフォルトの入力値。ユーザーがカスタム値を指定していない場合、ステップはこの値を使用します。設定されていない場合は、 required フィールドを真に設定してください。

required

必須:: いいえ
タイプ:: Boolean

ユーザーが TeamCity レシピ設定ページで入力値を指定する必要がある場合は真を返し、それ以外の場合は偽を返します。入力に デフォルト 値がない場合、この設定を有効にしてください。

ステップ

ビルド中に実行される一連のアクション。レシピは標準の TeamCity ビルドステップのカスタムバージョンを使用する一般化されたビルドステップですが、YAML レシピは、インストールされているツールに関係なく、どの TeamCity エージェントとも互換性がある汎用的なものとして設計されています。そのため、レシピステップでは現在、 Kotlin スクリプト、コマンドライン (スクリプト) ステップ、その他の YAML レシピのみを使用できます。

一般的な手順は次のようになります。

name: My step
script/kotlin-script/uses: <value>
<containerSettings>

  

レシピ .yml ファイルでは、個々のステップの定義は steps ブロック内に配置されます。

steps:
   - name: First step
     ...
   - name: Second step
      ...
   - name: Third step
      ...

  

お名前

必須:: いいえ
タイプ:: 文字列

公開ステップ名。非公開レシピの場合は無制限、公開レシピの場合は最大 100 文字です。

スクリプト

必須:: いいえ
タイプ:: 文字列

TeamCity コマンドライン (スクリプト) ステップを使用してカスタムスクリプトを実行するステップを指定します。公開レシピのスクリプトの最大文字数は 50000 文字です。例: 以下のステップはビルドログに「Hello world」を出力します。

name: Script step
script: echo "Hello world"

kotlin-script

必須:: いいえ
タイプ:: 文字列

TeamCity Kotlin スクリプトステップを使用してカスタム Kotlin スクリプトを実行するステップを指定します。公開レシピのスクリプトの最大文字数は 50000 文字です。例: 以下のステップはビルドログに「Hello world」を出力します。

name: Kotlin script step
kotlin-script: print("Hello world")

使用

必須:: いいえ
タイプ:: 文字列

この TeamCity サーバーにインストールされ、現在のレシピが使用されている同じプロジェクトで利用可能な別のレシピを参照します。フィールドの値は、参照先のレシピが公開レシピか非公開レシピかによって異なります。

公開レシピ: uses: namespace/recipe-name@major.minor.patch
プライベートレシピ: uses: private/recipe-name

参照先のレシピに必要な入力がある場合は、 inputs ブロックでその値を指定できます。

次のレシピステップは、バージョン "1.2.3" の jetbrains/some_recipe レシピを実行し、 foo と bar 値をそれぞれ some_recipe 入力 "input1 "と"input2" に渡します。

name: Custom step
uses: jetbrains/some_recipe@1.2.3
inputs:
   input1: foo
   input2: bar

    

container

必須:: いいえ
タイプ:: ContainerSettings オブジェクトまたは文字列

このステップを実行する Docker コンテナーまたは Podman コンテナーを指定します。このステップのレシピ全体の container フィールドをオーバーライドします。

以下のレシピステップは、Linux の「alpine」コンテナーで実行されます。

name: Container script step
container:
   image: alpine
   platform: linux
script: echo "Hello world"

    

イメージ名のみを指定する短い形式を使用できます。

name: Container script step
container: alpine
script: echo "Hello world"

    

サンプル

以下の YAML マークアップは、2 つの入力を持つシングルステップのレシピを宣言しています。レシピステップは、 input_name と input_value の入力値を使用して、 setParameter サービスメッセージを作成する Kotlin スクリプトを実行します。このサービスメッセージがビルドログに出力されると、TeamCity は お名前 パラメーターを見つけ、それに 値 を割り当てます。

このレシピは TeamCity チームによって作成され、JetBrains Marketplace で入手できます: jetbrains/set-environment-variable。

name: jetbrains/set-environment-variable
version: 1.0.0
description: |
  Sets the environment variable to the required value, creating it if absent.
inputs:
  - env.input_name:
      type: text
      required: true
      label: Name
      description: |
        The name of the environment variable to change, without the “env.” prefix. 
        Examples: “PATH”, “JAVA_HOME”, “DOTNET_ROOT”.
  - env.input_value:
      type: text
      required: true
      label: Value
steps:
  - name: Set environment variable
    kotlin-script: |-
      
      @file:Repository("https://download.jetbrains.com/teamcity-repository/")
      @file:DependsOn("org.jetbrains.teamcity:serviceMessages:2024.12")
      
      import jetbrains.buildServer.messages.serviceMessages.ServiceMessage
      import jetbrains.buildServer.messages.serviceMessages.ServiceMessageTypes.BUILD_SET_PARAMETER
      
      val message = ServiceMessage.asString(
          BUILD_SET_PARAMETER,
          mapOf(
              "name" to "env.${requiredInput("name")}",
              "value" to requiredInput("value")
          )
      )
      println(message)
      
      fun requiredInput(name: String) = System.getenv("input_$name") ?: error("Input '$name' is not set.")

  

2026 年 9 月 11 日