TeamCity On-Premises 2026.2 Help

レシピの操作について

レシピ は、単一または複数の標準 TeamCity ステップに基づくカスタムビルドステップです。 TeamCity の組み込みステップに必要なオプションがなく、頻繁に代用している場合 (たとえば、クラウドプロバイダー API 経由でアーティファクトをアップロードするために CLI ステップを使用する場合)、このカスタムステップを再利用可能なレシピとして保存できます。

レシピの作成は、カスタムビルドステップを実装する TeamCity プラグインの開発よりも簡単な代替手段です。

鍵となるポイント

レシピとは何ですか？
レシピは、特定の方法で事前設定されたデフォルトの TeamCity ビルドステップから作成されるカスタムビルドステップです。 複雑なレシピには、他のレシピをビルドブロックとして含めることができます。

レシピの目的は何ですか？
レシピを使用すると、事前にカスタマイズされた TeamCity ビルドステップを新しいステップにまとめ、ビルド構成間で簡単に共有できます。

レシピとメタランナーの違いは何ですか？
バージョン 2025.03 では、「メタランナー」は「レシピ」に名前が変更されました。 同じ概念に基づいていますが、レシピには YAML サポートや JetBrains マーケットプレイスでの簡単な共有などの追加の利点があります。

既存のメタランナーと TeamCity Meta-Runner Pack を引き続き使用できますか？
はい、メタランナーは新しい名前でも引き続き機能し、手動更新は不要です。

公開レシピとは何ですか？
公開レシピとは、 JetBrains マーケットプレイス(英語)で共有されているレシピです。 これには、JetBrains が手作業で作成したレシピと、他の TeamCity ユーザーが共有したレシピの両方が含まれます。

公開レシピは安全ですか？
JetBrains マーケットプレイスに掲載されているすべてのレシピは、当社の従業員による手動検証を受けています。 サーバーにインストールする前に、レシピのソースコードを確認することを お勧めします(英語)。 ソースコードにアクセスするには、レシピのマーケットプレイスページにある ソースコード リンクをクリックしてください。

レシピを作成したい場合は、どうすればよいですか？
カスタムビルドステップとして保存したいアクションを実行する既存のビルド構成を見つけるか、新しく作成し、 レシピを抽出するには TeamCity UI の構成 アクション メニューを使用します。 これにより、XML レシピを保存できます。 YAML レシピを作成するには、定義を一から記述する必要があります。 Marketplace で公開されているレシピのソースコードを確認し、 レシピ YAML の構文 の記事で詳細をご確認ください。

レシピの使い方は？
通常のビルド手順を利用するのと同じように: 構成の「ビルドステップ」リストに 追加します。

レシピは編集できますか？
はい、変更を加えるたびにソース構成を再構成してレシピを再抽出する必要はありません。 プライベートレシピは、 プロジェクト設定の レシピ ページで 編集できます。 パブリックレシピは外部の関係者によって作成されており、直接編集することはできません。

ビルド構成からレシピを抽出する

新しいレシピを作成する最も分かりやすい方法は、必要なステップまたは一連のステップを使用する既存の構成から抽出することです。 たとえば、以下の Kotlin DSL の例では、2 つの CLI ビルドステップを持つビルド構成を示しています。一方は cURL を使用してファイルをダウンロードし、もう一方は ls コマンド を実行して作業ディレクトリの内容を一覧表示します。

import jetbrains.buildServer.configs.kotlin.* object SourceConfiguration : BuildType({ name = "Source Configuration" params { param("URL", "") param("fileName", "") } steps { script { id = "simpleRunner" scriptContent = "curl -o %URL% %fileName%" } script { id = "simpleRunner_1" scriptContent = "ls" } } })

既存の構成からレシピを抽出するには:

  1. 構成設定で、 アクション メニューを呼び出し、 レシピの抽出 をクリックします。

    レシピの抽出

  2. ポップアップダイアログで、レシピの内部 ID、公開名、説明を入力します。 レシピは、これらの文字列を ビルドステップを追加ページに表示されます。

  3. 新しいレシピを作成するには、 抽出 をクリックします。 レシピは次のようになります。

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

レシピは <TeamCity データディレクトリ>\config\projects\<プロジェクト_ID>\pluginData\metaRunners ディレクトリに保存されます。 レシピは、構成がソースとして使用されたプロジェクトによって所有されます。 そのため、デフォルトでは、レシピは元のプロジェクトとそのサブプロジェクトでのみ使用できます。

レシピを使用する

レシピはカスタムビルドステップであるため、同じ方法でビルド構成に追加されます。

  1. 構成設定を開き、 ビルドステップ設定タブに移動します。

  2. ビルドステップを追加 ボタンをクリックしてください。

  3. 右側の列から次のレシピを選択します。

    • このプロジェクトまたはその親プロジェクトが所有するプライベートレシピ。

    • JetBrains マーケットプレイスからの公開レシピ。

    レシピを追加する

  4. 通常の TeamCity ステップと同じ方法で、必要なレシピ設定を設定します。

TeamCity 開発者や他の TeamCity ユーザーが作成した公開レシピは、 https://plugins.jetbrains.com/teamcity_recipe で詳しく見ることができます。 今後のリリースサイクルでコレクションを拡充していく予定のため、皆様のアイデアやフィードバックをお待ちしております。

Marketplace レシピオプションが表示されない場合は、プロジェクトで有効になっていることを確認してください。

  1. プロジェクト設定を開き、 レシピ設定タブに移動します。

  2. 公開 JetBrains Marketplace レシピ 設定を「有効」に切り替えます。 この設定が「無効」でグレー表示されている場合は、この動作を強制する親プロジェクトの設定を編集するか、このプロジェクトを管理している担当者に問い合わせてください。

ファイルからレシピをアップロードする

レシピの .xml 定義ファイルがある場合は、このファイルを必要なプロジェクトに手動でアップロードできます。 例: レシピをあるプロジェクトから別のプロジェクトに移動したり、 JetBrains マーケットプレイス(英語)からレシピを手動でダウンロードしたりする場合があります。

ファイルからレシピをインストールするには、次の手順を実行します。

  1. プロジェクト設定を開き、 レシピ設定タブに移動します。

  2. レシピをアップロードボタンをクリックしてください。

  3. 設定ファイルを選択し、一意のレシピ名を入力します。

  4. 保存をクリックします。 アップロードしたレシピは、このプロジェクトとそのサブプロジェクトのすべての構成で使用できるようになります。

既存のレシピを管理

プロジェクト設定の レシピ ページでは、次の操作を実行できます。

  • このプロジェクトとそのすべてのサブプロジェクトの公開 (マーケットプレイスベース) レシピを有効または無効にします。

  • このプロジェクトで使用されているすべてのパブリックおよびプライベートレシピをインスペクションし、使用状況を確認して問題を見つけます。

ルートプロジェクトのレシピページ

ルートプロジェクトのこのページを開くと、サーバー全体の使用状況レポートを確認できます。 レシピタグは、より新しいレシピバージョンが利用可能になった場合、現在のバージョンまたはレシピ全体が Marketplace で利用できなくなった場合、または TeamCity が JetBrains Marketplace に接続してレシピデータを取得できない場合に通知します。

Marketplace でレシピを共有

YAML ベースのレシピは、JetBrains Marketplace で TeamCity コミュニティと共有できます。 詳しくは、次の記事を参照してください: TeamCity レシピのアップロード。

プライベートレシピを編集

ビルド構成から抽出されたレシピ、またはファイルからアップロードされたレシピは、サーバーマシン上にローカルに保存され、TeamCity UI で編集できます。

  1. プロジェクト設定を開き、 レシピ設定タブに移動します。

  2. 設定ファイルを表示および編集するためのプライベートレシピ。

例: 既存の構成から抽出されたレシピは、この構成からすべてのパラメーターをコピーします。 レシピによって実行される実際のビルド手順に関係のないパラメーターは削除できます。

XML パラメーター仕様

XML レシピパラメーター仕様は spec="type 属性='値' 形式です。 この仕様を編集することで、パラメーター／エディターの外観や動作設定を変更できます。

<parameters> <param name="internalName" value="" spec="type attribute1='value1' attribute2='value2'/> </parameters>

例:

# Checkbox parameter <param name="enabled" value="" spec="checkbox checkedValue='true' uncheckedValue='false' label='Enable debug' description='Tick this setting to run in debug mode'"/> # Select parameter <param name="logBehavior" value="" spec="select data_1='All' data_2='Errors only' data_3='Errors and warnings' label='Logging verbosity:' description='Choose whether only critical or all messages should be logged'"/> # Prompt parameter that cannot have an empty value <param name="tag" value="default" spec="text description='This value cannot be empty' label='Tag: ' validationMode='not_empty' display='prompt'" />

レシピの自律性

レシピはビルド構成全体で再利用できるように設計されているため、構成に依存しません。 つまり、レシピは理想的には、他の構成設定に関係なく実行できるアクションを実行する必要があります。

さらに、レシピには元のビルドステップと同じプロジェクト要件があります。 レシピをできるだけ多くのビルドエージェントと互換性を持たせるために、クロスプラットフォームビルドステップ (コマンドライン (スクリプト) や Kotlin スクリプト など) をレシピのベースとして選択することもできます。

例 1: VCS ルート

VCS のルートはレシピ設定ファイルに組み込まれていません。 そのため、リポジトリファイルとフォルダーに対して操作を実行するレシピを作成すると、適切な VCS ルートのない設定は失敗します。 このようなレシピが必要な場合は、次の操作を行います。

  1. レシピをインポートするビルド構成の 設定に移動します。

  2. バージョン管理設定 タブに切り替えます。

  3. VCS ルートを接続 ボタンをクリックしてください。

  4. 既存の VCS ルートを接続 では、元の構成で使用しているのと同じルートを選択します。

  5. ページの下部にある 保存 をクリックし、ビルド構成を実行します。 VCS リポジトリに接続できるようになったため、ビルドステップは必要なファイルにアクセスでき、正常に完了できます。

例 2: ビルドファイル

Gradle、 Maven、 Ant 、その他のビルドステップは、 ビルド.xml や pom.xml などのビルドファイルを処理します。 カスタムレシピにこのようなステップが含まれている場合は、インポートするビルド構成で必要なファイルを見つけられるようにして、失敗を回避してください。

パスを指定するだけでなく、ビルドファイルを直接定義できるビルドステップは、レシピでの使用に特に適しています。 例: Ant ビルドステップ。

Ant ステップ設定に埋め込まれたビルド構成ファイル

コンテナーでレシピを起動する

Docker/Podman コンテナー内で実行を実行できるビルドステップは、レシピ内で使用される場合もこの機能を保持します。 次のサンプルレシピマークアップでは、2 つのステップを定義します: Kotlin スクリプトステップは zenika/kotlin イメージ内で実行され、 コマンドライン (スクリプト) ステップにはコンテナー関連の設定がありません。

<meta-runner name="Kotlin-CLI-XML"> <description>Sample 2-step recipe</description> <settings> <parameters> <!-- TeamCity build parameters --> </parameters> <build-runners> <runner name="Kotlin step" type="kotlinScript"> <parameters> <param name="scriptType" value="customScript" /> <param name="scriptContent" value="// TODO" /> <!-- Docker image parameter --> <param name="plugin.docker.imageId" value="zenika/kotlin:1.1.61-alpine" /> </parameters> </runner> <runner name="CLI step" type="simpleRunner"> <parameters> <param name="script.content" value="# TODO" /> <param name="teamcity.step.mode" value="default" /> <param name="use.custom.script" value="true" /> </parameters> </runner> </build-runners> <requirements /> </settings> </meta-runner>
name: RecipeDemo_KotlinCliYaml title: Kotlin-CLI-YAML description: Sample 2-step recipe inputs: ... steps: - name: Kotlin step container: zenika/kotlin:1.1.61-alpine kotlin-script: // TODO - name: CLI step script: "# TODO"

ビルド構成にレシピを追加するときは、コンテナー設定セクションでレシピ全体のイメージを定義できます。 ステップで独自のコンテナー設定を指定していない限り、このイメージはすべてのステップに適用されます。指定した場合は、その設定が優先されます。

例: 以下の バージョン付き設定は、ビルド構成内で同じサンプルレシピを示しています。 この構成では、レシピは ubuntu:rolling イメージで実行されます。 コマンドラインステップではこのイメージが使用され、Kotlin ステップではこのグローバル設定がオーバーライドされ、 zenika/kotlin で実行されます。

<?xml version="1.0" encoding="UTF-8"?> <build-type xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://www.jetbrains.com/ja-jp/teamcity/schemas/2025.3/project-config.xsd" uuid="12345"> <name>MyBuildConfig</name> <description /> <settings> <build-runners> <runner id="RecipeDemo_KotlinCliYaml" name="" type="RecipeDemo_KotlinCliYaml"> <parameters> <param name="plugin.docker.imageId" value="ubuntu:rolling" /> <!-- Other recipe parameters --> </parameters> </runner> </build-runners> </settings> </build-type>
object MyBuildConfig : BuildType({ name = "Sample configuration" steps { step { id = "RecipeDemo_KotlinCliYaml" type = "RecipeDemo_KotlinCliYaml" executionMode = BuildStep.ExecutionMode.DEFAULT param("plugin.docker.imageId", "ubuntu:rolling") // Other recipe parameters } } })

Docker で実行 ビルド機能にも同じ優先ルールが適用され、ビルド構成全体にグローバルな Docker/Podman イメージが設定されます。 このイメージは、レシピとそのステップで独自のコンテナー設定が定義されていない場合にのみ使用されます。

2026 年 9 月 11 日
ビルドステップ実行条件レシピ YAML の構文