TeamCity オンプレミス 2026.1 ヘルプ

レシピの操作

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

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

重要なポイント

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

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

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

既存のメタランナーと TeamCity メタランナーパック(英語)を引き続き使用できますか？ ？ は
い、メタランナーは新しい名前でも引き続き機能し、手動での更新は必要ありません。

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

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

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

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

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

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

新しいレシピを作成する最も簡単な方法は、必要なステップまたは一連のステップを使用する既存の構成からレシピを抽出することです。例: 以下の Kotlin DSL の例は、2 つの CLI ビルドステップを含むビルド構成を示しています。1 つは cURL を使用してファイルをダウンロードし、もう 1 つは 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. 構成設定で、アクションメニューを呼び出し、レシピの抽出をクリックします。

    Extract recipe

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

レシピを使う

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

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

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

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

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

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

    Add a recipe

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

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

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

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

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

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

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

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

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

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

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

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

既存のレシピを管理する

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

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

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

Recipes page in Root project

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

マーケットプレイスでレシピを共有する

YAML ベースのレシピは、JetBrains マーケットプレイスの TeamCity コミュニティと共有できます。詳しくは、こちらの記事を参照してください: TeamCity レシピのアップロード (英語)

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

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

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

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

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

XML パラメーター仕様

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

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

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

Build config file embedded in Ant step settings

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

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

<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/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 イメージが設定されます。このイメージは、レシピとそのステップで独自のコンテナー設定が定義されていない場合にのみ使用されます。

2025 年 10 月 27 日
ビルドステップの実行条件 レシピ YAML 構文

関連ページ：

コマンドライン (スクリプト)

コマンドライン（ビルド構成内）またはスクリプト（パイプライン内）は、TeamCity の中で最も柔軟なビルドステップです。エージェントマシン上で直接コマンドを実行するため、インストールされている任意のツール（cURL、Homebrew、Python、Unreal Engine など）との連携が可能になります。ツール固有の TeamCity ステップの代替として使用することもできます。たとえば、ゴールで Maven ステップを使用する代わりに、スクリプトを実行します。ステップ設定：スクリプトステップ...

レシピ YAML 構文

このドキュメントでは、YAML レシピの一般的な構文について説明します。カスタム YAML レシピを作成するには、.yml 定義ファイルを作成し、TeamCity (プロジェクト設定 | レシピ | プライベートレシピをアップロード) にアップロードしてください。共通レシピ構造：TeamCity YAML レシピの構造は次のとおりです。name: myorg/recipe-name title: The recipe title version: 1.2.3 description: The reci...

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

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

Kotlin DSL

TeamCity では、バージョン管理で設定を XML 形式で保存するだけでなく、DSL (Kotlin 言語に基づく) で設定を保存することもできます。バージョン管理に保存された DSL を使用すると、プログラムで設定を定義できます。Kotlin は静的に型指定されるため、IDE で自動補完機能を自動的に受け取ります。これにより、利用可能な API オプションの発見がはるかに簡単になります。TeamCity での Kotlin DSL の使用に関するブログ投稿シリーズと推奨リファクタリングの記...

ビルドステップの設定

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

TeamCity データディレクトリ

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