レシピ 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 マーケットプレイスの名前です。同じユーザーがアップロードしたレシピはすべて、同じ名前空間を持つ必要があります。ユーザー名前空間の管理について詳しくは、マーケットプレイスのドキュメント記事（TeamCity レシピのアップロード(英語)）を参照してください。

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

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

タイトル

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

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

バージョン

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

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

description

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

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

コンテナー

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

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

入力

必須 : いいえ
タイプ : リスト <Input>

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

手順

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

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

コンテナー設定

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

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

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

container: alpine

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

画像

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

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

プラットフォーム

必須 : いいえ
タイプ : 弦
サポートされている値 : 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:
      ...

<input-name>

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

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

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

環境変数 (推奨)

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

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

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

型

必須 : はい
タイプ : 弦
サポートされている値 : text | boolean | select | password

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

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

ラベル

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

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

description

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

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

デフォルト

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

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

必須

必須 : いいえ
タイプ : Boolean

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

ステップ

ビルド中に実行される一連のアクション。レシピは、標準の 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")

use

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

この 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

コンテナー

必須 : いいえ
タイプ : 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 は name パラメーターを見つけ、それに value を割り当てます。

このレシピは TeamCity チームによって作成され、JetBrains マーケットプレイスで入手できます: 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.")

2025 年 7 月 17 日

関連ページ：

レシピの操作

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

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

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

ビルドステップの設定

ビルドステップは、CI/CD ワークフローの最小単位です。ビルドステップは、全体として実行される一連のアクションを定義します。ビルドステップは、ビルド構成とパイプラインジョブに属します。構成とパイプラインのビルドステップ：TeamCity は、.NET、Maven、NAnt、Xcode などの特定のビルドツール用に設計された幅広いビルドステップを提供します。現在、ビルド構成ではすべてのステップが利用可能です。バージョン 2025.07 で導入された

Docker で実行

Docker で実行ビルド機能を使用すると、ビルド構成のすべてのステップを同じ Docker または Linux コンテナー内で実行できます。以下は、コンテナー内で起動できるビルドステップのリストです。コマンドライン、Maven、Ant、Gradle、.NET、Python、PowerShell、C# スクリプト、Node.js、

接続を構成

TeamCity 接続は、外部サービスへのアクセスに必要な資格情報を保存します。このサードパーティサービスの種類に基づいて、2 つの主要な接続カテゴリがあります。VCS 接続これらの接続は、GitHub、GitLab、Bitbucket クラウドなどの VCS プロバイダーへのアクセスに必要な情報を保存します。これらの接続は、プロジェクト、ビルド構成、パイプラインを最も速く作成する方法を提供します。認証は自動的に処理されるため、リポジトリを選択するだけでビルドステップの設定を開始できます。接続が...

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

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