ビルドステップの設定

ビルドステップは、CI/CD ワークフローの最小単位です。ビルドステップは、全体として実行される一連のアクションを定義します。ビルドステップは、ビルド構成とパイプラインジョブに属します。

構成とパイプラインのビルドステップ

TeamCity は、 .NET、 Maven、 NAnt、 Xcode など、特定のビルドツール向けに設計された幅広いビルドステップを提供します。

現在、ビルド構成ではすべてのステップが利用可能です。バージョン 2025.07 で導入されたパイプラインは、一部のサブセットをサポートしています。ただし、スクリプトステップはエージェントマシンにインストールされている任意のツールでコマンドを実行できるため、あらゆるタイプのプロジェクトをビルドできます。

TeamCity UI 経由でステップを追加

ビルド構成

構成設定を開き、 ビルドステップ設定タブに移動します。
ビルドステップを追加をクリックしてビルドステップを手動で選択するか、ビルドステップを自動検出をクリックして、TeamCity に VCS ルートが対象とするリモートリポジトリをスキャンさせ、適切なステップを提案させます。
リポジトリをスキャンするとき、TeamCity はソースツリーの上位 2 階層内にあるプロジェクトファイルを探し、ファイル拡張子で識別します。例:
- PowerShell： .ps1
- .NET: project.json、 .proj、 .csproj、 .vbproj、 .sln
提案されたステップがすでに構成に追加されている場合、TeamCity はそのステップを推奨から除外します。

新しいビルドステップページには 2 つの列が含まれます。

デフォルトの手順 - JetBrains によって事前定義されています。
レシピ (旧称メタランナー) - TeamCity コミュニティまたはチームが作成したカスタム XML または YAML ステップ。

JetBrains マーケットプレイスの公開レシピへのアクセスは、プロジェクト設定によって異なります。詳しくは、レシピの操作についての記事を参照してください。

パイプライン

ジョブ設定を開き、サイド設定パネルのステップセクションまでスクロールします。
任意のタイルをクリックして、対応するビルドステップを追加します。

コードでステップを追加

TeamCity は、 configuration-as-code を Kotlin DSL および YAML (現在はパイプラインのみ) 形式でサポートしています。

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.maven
import jetbrains.buildServer.configs.kotlin.buildSteps.script

object SampleConfig: BuildType({
    name = "Sample two-step configuration"
    steps {
        script {
            name = "Step 1"
            id = "simpleRunner"
            scriptContent = """echo "Hello world""""
        }
        maven {
            name = "Step 2"
            id = "Step_2"
            goals = "clean package"
            jdkHome = "%env.JDK_21_0_ARM64%"
            mavenVersion = custom {
                path = "%teamcity.tool.maven.3.8.6%"
            }
        }
    }
})

    

Job1:
    name: Sample two-step job
    steps:
      - type: script
        name: Step 1
        script-content: echo "Hello world"
      - type: maven
        name: Step 2
        pom-location: pom.xml
        goals: clean package
        jdk-home: '%env.JDK_21_0_ARM64%'
        maven-version:
          bundled_3_8: {}

    

ステップ実行条件

ビルドステップは、UI または構成コードに表示されている順序で、上から下へと実行されます。デフォルトでは、TeamCity はいずれかのステップが失敗するまですべてのステップを実行します。いずれかのステップが失敗すると、ビルドは失敗としてマークされ、残りのステップはスキップされます。

ステップをいつ実行するかを定義するカスタム実行ポリシーを設定することで、ビルド構成でこの動作をオーバーライドできます。

実行条件は 2 つの部分で構成されます。

対応するドロップダウンメニューから選択された一般的なルール。
条件を追加メニューからオプションの追加条件が追加されます。

一般的な実行ルール

ビルドステータスが成功の場合のみ — ステップを開始する前に、ビルドエージェントはサーバーにビルドステータスを要求し、ステータスが「失敗」の場合はステップをスキップします。これは、テスト失敗やメトリクス変更による失敗など、サーバーによって処理される失敗条件を考慮します。一部の障害条件はサーバー上で非同期的に処理されるため (TW-17015(英語) )、これは依然として正確ではない可能性があることに注意してください。
ビルドステータスが失敗の場合のみ — 上記と同じですが、ビルドステータスが「成功」の場合、エージェントはこのステップをスキップします。この条件は、ロールバックやクリーンアップアクションに役立ちます。
以前のすべてのステップが正常に完了した場合 — エージェント上の前のすべてのステップが成功した場合、サーバーによって報告されたビルドステータスをチェックせずに実行されます。
以前のステップの一部が失敗した場合でも — 前のステップの結果やビルドの状態に関係なく実行されます。
ビルド停止コマンドが発行された場合でも常にに — ビルドがキャンセルされた場合でも、ステップが確実に実行されます。例: 2 つのステップでこの設定を使用し、最初のステップでビルドが停止した場合でも、2 番目のステップは実行されます。 2 番目の停止コマンドはビルドを完全に終了します。

追加条件

カスタム条件を使用して実行動作を調整できます。たとえば、個人ビルドまたはデフォルト以外のブランチのステップをスキップしたり、 teamcity.agent.jvm.os.name パラメーター値をチェックして OS 固有のステップを実行したりします。

詳細については、次のトピックを参照してください: ビルドステップ実行条件。

Bootstrap ステップ

ブートストラップステップは、ビルドがトリガーされた直後、ビルドエージェントがソースファイルをチェックアウトする前に実行されます。これにより、初期セットアップを実行し、後続のステップが期待どおりに実行されるようにするランナー (通常はコマンドライン (スクリプト)) を追加できます。

ブートストラップステップを有効化するには、まず teamcity.internal.bootstrap.steps.enabled=true エントリを TeamCity 内部プロパティまたは個別のプロジェクト (このプロジェクトの構成パラメーターとして) に追加します。この設定により、次の操作を実行できます。

ステップ設定でブートストラップ中に実行オプションを有効化します。
構成のビルドステップページでビルド手順を並べ替えるをクリックし、必要なステップを "準備ステージ" ブロックの前にドラッグします。

ブートストラップステップを使用してビルド構成を作成し、この構成をテンプレートに変換できます。このようなテンプレートを使用すると、実際のビルドプロセスが開始される前に、必要な前提条件アクションを実行する追加の構成をすばやく作成できます。

レシピは単一のステップとして扱われるため、チェックアウトの前後に実行される部分に分割することはできません。

Kotlin DSL で通常のステップをブートストラップステップに変換するには、 teamcity.step.phase パラメーターを追加し、その値を「bootstrap」に設定します。

object MyConfig : BuildType({
  // ...
  steps {
    script {
      name = "Disk prep"
      id = "simpleRunner"
      scriptContent = "echo 'Initial setup'"
      param("teamcity.step.phase", "bootstrap") // Bootstrap step
    }
    // Regular steps
  }
  // ...
})

  

エージェントレスビルドステップ

エージェントレスのビルド手順は、ビルドエージェントを接続せずに外部ソフトウェアで実行できるステップです。

通常、実行中のビルドは、最後のステップが TeamCity の外部で実行される場合でも、最後までビルドエージェントを占有します。ただし、ビルドが残りのいくつかのステップでエージェントを必要としない場合は、このエージェントからデタッチできます。エージェントが使用可能になり、すぐに別のビルドに割り当てることができます。

この方法では、エージェントの作業時間を節約でき、ビルドを完了させるためにサードパーティツールを使用する構成に最適です: たとえば、多数のテストを実行したり、プロジェクトをデプロイしたりする場合です。このようなビルドは TeamCity の外部で完了できます。TeamCity サーバーは、エージェントを仲介役として使用せずに、ステータスレポートを直接検出します。

コンパイル、テスト、デプロイの 3 つのステップで構成されるビルドの例を考えてみましょう。デプロイステップは実際には外部ソフトウェアによって実行されますが、これらはすべてエージェントによって処理されます。エージェントは、外部ソフトウェアをポーリングし、ビルドステータスを TeamCity サーバーに報告しているだけです。

エージェントレスアプローチでは、エージェントは最後のデプロイステップを処理する必要がなく、キューから他のビルドを実行できます。 TeamCity サーバーは、外部ツールから次のレポートを直接受け取ります。

関連事項: ビルドをエージェントからデタッチ

ステップステータスのパラメーター

TeamCity は、指定された ID のステップのステータスを報告する teamcity.build.step.status.<ステップ_ID> パラメーターを提供します。これらのパラメーターは、たとえば、きめ細かな実行条件の作成に使用できます。

ステップ ID は名前に表示され、作成時にのみ編集できます。

teamcity.build.step.status.<ステップ_ID> パラメーターの使用可能な値は次のとおりです。

成功 — ステップがエラーなしで終了したとき。
失敗 — ステップが失敗したとき。このステータスは、すべてのビルドの問題がミュートされている場合でも報告されます。
キャンセル — このステップの実行中にビルドがキャンセルされたとき。

teamcity.build.step.status.<ステップ_ID> パラメーターは、対応するステップが終了した後にのみ表示され、ビルドの開始直後からは使用できません。これは、まだ実行中のステップも、スキップされたステップも、使用可能な teamcity.build.step.status.<ステップ_ID> パラメーターがないことを意味します。

すべてのステップのステータスは、ビルド結果ページのパラメータータブで確認できます。

... または TeamCity REST API 経由。

http://<SERVER_URL>/app/rest/builds/<BUILD_ID>/resulting-properties

追加情報

元のビルド構成設定ページから、あるビルド構成から別のビルド構成にビルドステップをコピーできます。
必要に応じてビルドステップを並べ替えることができます。テンプレートから継承されたビルド構成がある場合、継承されたビルドステップを並べ替えることはできないことに注意してください。ただし、カスタムビルドステップ（継承されない）は、継承されたビルドステップの前または間にある場合でも、任意の場所および順序で挿入できます。継承されたビルドステップは、元のテンプレートでのみ並べ替えることができます。
ビルド構成テンプレートから継承されている場合でも、ビルドステップリストの最後の列にある対応するオプションを使用して、ビルドステップを一時的または永続的に無効にすることができます。

2026 年 9 月 11 日