TeamCity オンプレミス 2024.03 ヘルプ

プルリクエスト

プルリクエスト ビルド機能は、GitHubBitbucket サーバーBitbucket クラウドGitLabAzure DevOpsJetBrains Space リポジトリの pull (マージ) リクエストとの TeamCity 統合を強化します。

共通情報

ビルド構成にプルリクエスト機能を追加すると、次のことが可能になります。

  • ビルド構成の概要ページで、プルリクエストブランチと保留中の変更を表示します。

    New pull branches on the main build configuration page
  • ビルド結果ページ概要タブでプルリクエストの詳細を表示します。

    Pull request details

    ドラフトプルリクエストの場合、アイコンはグレー表示になり、プルリクエスト番号の前に下書きステータスが表示されます。

    Pull request details
  • 監視するプルリクエストを制御する特定の基準を設定します。プルリクエストは、作成者、ターゲット、送信元ブランチでフィルタリングできます。

  • 開発者がローカルのブランチで作業し、プル (マージ) リクエストとして送信されない限り、TeamCity がこれらの変更を構築するためにリソースを無駄にしないワークフローを設定します (VCS ルートとのやり取りセクションを参照)。

プルリクエスト機能は、プル (マージ) リクエストブランチに対して新しいビルドを自動的にトリガーしません。プルリクエストブランチからの変更をメインコードベースにマージする前に評価するには、必要なブランチ (たとえば、GitHub の場合は refs/pull/*) をターゲットとする VCS トリガーを追加します。TeamCity UI で作成された新しいビルド構成には、+:* 仕様のトリガーがすでに含まれており、これにより、TeamCity はプル (マージ) リクエストブランチからの変更をビルドできます。

プロジェクトが GitHub または GitLab リポジトリを対象としている場合は、TeamCity にプルリクエストブランチをビルドさせ、ビルドが成功したリクエストをマージすることで、セットアップをさらに自動化できます。これを行うには、プルリクエストに加えて自動マージビルド機能を追加します。

VCS ルートとのやり取り

プルリクエスト機能は、現在のビルド構成に添付されている VCS ルートの元のブランチ仕様を拡張します。そのため、あいまいで予期しない動作を回避するために、VCS ルートのブランチ仕様には、プルリクエストブランチに一致するパターンを含めないでください。

プルリクエストのみをビルドする場合は、VCS ルートのブランチ仕様をクリアします。

object MyRepoRoot : GitVcsRoot({ name = "MyRoot" url = "https://github.com/username/reponame" branch = "refs/heads/main" // the "branchSpec = ..." parameter is missing })

以下のサンプルは、ルートブランチ仕様とプルリクエスト機能が相互に補完し、次のワークフローを実装するように、TeamCity プロジェクトを正しく設定する方法を示しています。

  • TeamCity は、mainproductionsandbox ブランチと、「release-」で始まるすべてのブランチ (たとえば、release-2077.02) のみを追跡します。

  • 開発者は、TeamCity に触れることなく、ローカルのブランチを作成し、それを操作できます。

  • 開発者が変更を公開する準備ができたら、個人用 (追跡されていない) のコミットをコア (追跡されている) ブランチにマージするリクエストを作成できます。これにより、新しいプルブランチ (たとえば、GitHub 上の refs/pull/54) が作成されます。プルリクエスト機能により、この新しいブランチが検出され、マージされる前に TeamCity で変更をビルドしてテストできるようになります。

  • 機能の作成者で絞り込む設定により、TimCity は、許可されていない (外部) ユーザーの要求に対して作成された同様の refs/pull/<Int> ブランチを無視します。

project { vcsRoot(MyRepoRoot) buildType(Build) } object Build : BuildType({ name = "Build" vcs { root(MyRepoRoot) } // ... features { pullRequests { vcsRootExtId = "${MyRepoRoot.id}" provider = github { authType = vcsRoot() filterAuthorRole = PullRequests.GitHubRoleFilter.MEMBER } } } }) object MyRepoRoot : GitVcsRoot({ name = "MyRoot" url = "https://github.com/username/reponame" branch = "refs/heads/main" branchSpec = """ refs/heads/main refs/heads/production refs/heads/sandbox refs/heads/release-* """.trimIndent() })

VCS 固有の設定

GitHub プルリクエスト

この機能は、GitHub(英語) および GitHub Enterprise(英語) をサポートします。refs/pull/*/head ブランチでのみビルドを監視します。

GitHub ホスティング型では、次のパラメーターを使用できます。

パラメーター

オプション

説明

認証タイプ

VCS ルート認証情報を使用する

TeamCity は、VCS ルートが HTTP(S) フェッチ URL を使用する場合、VCS ルート設定からユーザー名 / パスワード認証情報または個人アクセストークン /x-oauth-basic を抽出しようとします。

VCS ルートが匿名認証または SSH を採用している場合、このオプションは機能しません。

GitHub Enterprise リポジトリの場合、個人アクセストークン /x-oauth-basic ペアのみが機能します。

アクセストークン

個人用アクセストークンを使用するか、OAuth 接続を介してトークンを取得します。public_repo (パブリックリポジトリ用)または repo (プライベートリポジトリ用)スコープのいずれかが必要です。

GitHub アプリのアクセストークン

GitHub アプリ経由で発行された非個人的な有効期間の短いトークン。このオプションは、VCS ルート設定が特定の VCS ルートを指しており、このルートが GitHub アプリ接続を使用して設定されている場合にのみ使用できます。

作成者による

このフィルターは、公開リポジトリにのみ適用されます。

同じ組織のメンバー

GitHub の同じ組織のメンバー(英語)によって送信されたプルリクエストのみを検出します。

メンバーと外部の協力者

同じ組織のメンバーと GitHub の外部の共同エディター(英語)によって送信されたプルリクエストのみを検出します。

みんな

すべてのプル要求を検出します。このオプションを選択すると、任意のユーザーがビルドエージェントで悪意のあるコードを実行できる可能性があることに注意してください。

ソース別ブランチ

ブランチフィルターを定義して、指定された基準に一致するソースブランチのプルリクエストのみを監視します。空のままにすると、フィルターは適用されません。

ターゲットブランチ

ブランチフィルターを定義して、指定された基準に一致するターゲットブランチでのみプルリクエストを監視します。空のままにすると、フィルターは適用されません。

下書きを無視

デフォルトでは、プルリクエストビルド機能は GitHub ドラフトプルリクエスト(英語)情報をロードし、ドラフトプルリクエストに基づいてビルドを実行します。ビルドページでは、マージリクエスト番号の横にグレー表示のアイコンと下書きステータスが表示されます。

チェックボックスをオンにして、GitHub ドラフトプルリクエストを無視します。TeamCity は、ステータスが変更されるまでドラフトプルリクエスト情報をロードしません。

サーバー URL

接続用の GitHub URL を指定します。

空のままにすると、URL は VCS ルートフェッチ URL から抽出されます。

Bitbucket サーバー / データセンターのプルリクエスト

Bitbucket サーバー / データセンター(英語)ホスティング型では、次のパラメーターを使用できます。

パラメーター

説明

認証タイプ

  • VCS ルート認証情報を使用する — VCS ルートが HTTP(S) フェッチ URL を使用している場合、TeamCity は VCS ルート設定からユーザー名 / パスワード認証情報を抽出しようとします。VCS ルートが SSH フェッチ URL を使用している場合、または匿名認証を使用している場合、このオプションは機能しません。

  • ユーザー名パスワード — Bitbucket サーバー / データセンターに接続するためのユーザー名とパスワードを指定します。パスワードの代わりにアクセストークンを送信できます。トークンには、プロジェクトおよびリポジトリに対する読み取り権限が必要です。

  • リフレッシュ可能なアクセストークン — 構成された Bitbucket サーバー / データセンター OAuth 2.0 接続のリストを表示します。有効期間の短い OAuth トークンの発行に使用する接続の横にある取得ボタンをクリックします。

ユーザー名パスワード

Bitbucket サーバーに接続するためのユーザー名とパスワードを指定します。

パスワードの代わりにアクセストークンを送信できます。トークンには、プロジェクトとリポジトリの読み取り権限が必要です。

ソース別ブランチ

ブランチフィルターを定義して、指定された基準に一致するソースブランチのプルリクエストのみを監視します。空のままにすると、フィルターは適用されません。

ターゲットブランチ

ブランチフィルターを定義して、指定された基準に一致するターゲットブランチでのみプルリクエストを監視します。空のままにすると、フィルターは適用されません。

サーバー URL

接続用の Bitbucket URL を指定します。

空のままにすると、URL は VCS ルートフェッチ URL から抽出されます。

プルリクエストブランチを使用

このオプションは下位互換性のみを目的としています。ソースブランチの代わりに、正式にサポートされていない Bitbucket(英語) プルリクエストブランチ (pull-requests/*) の検出を有効にします。注意: 切り替え後、過去 1 時間以内にコミットされた変更に対して、新しいビルドがトリガーされる場合があります。

Bitbucket クラウドプルリクエスト

Bitbucket Cloud はプルリクエスト専用のブランチを作成しないため、このビルド機能はソースリポジトリ内のソースブランチを直接監視します (フォークはサポートされていません)。
ビルド開始時に同じソースブランチから複数のプルリクエストが送信された場合、TeamCity はビルド結果にこれらすべてのリクエストを表示します。ただし、フィルタリング基準に一致するオープン PR からのコミットのみがビルドの変更として表示されます。

VCS ルートのブランチ仕様には、プル要求ブランチに一致するパターンが含まれていてはならないことに注意してください。

Bitbucket クラウド(英語)ホスティング型では、次のパラメーターを使用できます。

設定

説明

認証タイプ

  • VCS ルート認証情報を使用する — VCS ルートが HTTP(S) フェッチ URL を使用している場合、TeamCity は VCS ルート設定からユーザー名 / パスワード認証情報を抽出しようとします。VCS ルートが SSH フェッチ URL を使用している場合、または匿名認証を使用している場合、このオプションは機能しません。

  • ユーザー名パスワード — Bitbucket クラウドに接続するためのユーザー名とパスワードを指定します。プルリクエストアプリのパスワード(英語)を使用することをお勧めします | スコープを読み取ります。

  • リフレッシュ可能なアクセストークン — 構成された Bitbucket クラウド OAuth 接続のリストを表示します。有効期間の短い OAuth トークンの発行に使用する接続の横にある取得ボタンをクリックします。

    PR Token for Bitbucket Cloud

  • パーマネントアクセストークン — Bitbucket リポジトリアクセストークン(英語)プロジェクトアクセストークン(英語)、またはワークスペースアクセストークン(英語)を入力して、リポジトリ、ワークスペース、プロジェクトへの長期アクセスを構成します。トークンはプルリクエスト | で構成する必要があります。読み取り範囲。

ターゲットブランチ

ブランチフィルターを定義して、指定された基準に一致するブランチのプルリクエストのみを監視します。空のままにすると、フィルターは適用されません。

GitLab マージリクエスト

TeamCity は、他のホスティングサービスでプルリクエストを処理する方法と同様に、GitLab マージリクエスト(英語)を処理します。現在、TeamCity は、このビルド機能を有効にした後に送信されたマージ要求のみを検出します。

この機能は、refs/merge-requests/*/head ブランチでのみビルドを監視します。

GitLab(英語) ホスティング型では、次のパラメーターを使用できます。

パラメーター

説明

認証タイプ

  • VCS ルート認証情報を使用する — VCS ルートが HTTP(S) フェッチ URL を使用している場合、TeamCity は VCS ルート設定からログイン認証情報またはアクセストークンを抽出しようとします。VCS ルートが匿名認証を使用している場合、このオプションは機能しません。

  • 個人アクセストークン — GitLab で発行された個人用アクセストークンを使用します。api スコープのいずれかが必要です。

  • GitLab アプリケーショントークン — 設定された GitLab OAuth 接続のリストを表示します。有効期間の短い OAuth トークンの発行に使用する接続の横にある取得ボタンをクリックします。

    PR Token for GitLab

ソース別ブランチ

ブランチフィルターを定義して、指定された基準に一致するソースブランチでのみマージ要求をモニターします。空のままにすると、フィルターは適用されません。

ターゲットブランチ

ブランチフィルターを定義して、指定された基準に一致するターゲットブランチでのみマージ要求をモニターします。空のままにすると、フィルターは適用されません。

下書きを無視

デフォルトでは、プルリクエストビルド機能は GitLab ドラフトマージリクエスト(英語)情報をロードし、ドラフトマージリクエストに基づいてビルドを実行します。ビルドページでは、マージリクエスト番号の横にグレー表示のアイコンと下書きステータスが表示されます。

GitLab ドラフトマージリクエストを無視するには、ボックスをオンにします。TeamCity はドラフトのマージリクエスト情報をロードせず、ステータスが非ドラフトに変わるまでマージリクエストは無視されます。

サーバー URL

接続用の GitLab URL を指定します。

空のままにすると、URL は VCS ルートフェッチ URL から抽出されます。

Azure DevOps プルリクエスト

この機能は、refs/pull/*/merge ブランチでのみビルドを監視します。

Azure DevOps(英語) の場合、TeamCity は、他の VCS のようにプル要求自体ではなく、マージブランチで要求を検出します。各ビルドは仮想ブランチで起動され、PR をマージした後のビルドの実際の結果を示します。ビルドには、変更を伴うコミットと仮想マージコミットの両方が含まれます。

この機能は Azure DevOps ドラフトプルリクエストを無視することに注意してください。

認証設定

  • 個人アクセストークンAzure DevOps アカウント設定で発行(英語)できる静的トークン。発行されたトークンには、プルリクエストが必要な情報を取得できるように Code (read) スコープが必要です。

  • リフレッシュ可能なアクセストークン — 構成された Azure OAuth 2.0 接続経由で発行される有効期間の短いトークン。必要な接続の横にある取得ボタンをクリックして、アクセストークンを取得します。

    Refreshable tokens for Azure DevOps

プルリクエストのフィルタリング

  • ソース別ブランチ — 指定された基準に一致するソースブランチ上のプルリクエストのみを監視するブランチフィルター。空のままにすると、フィルターは適用されません。

  • ターゲットブランチ — 指定された基準に一致するターゲットブランチ上のプルリクエストのみを監視するブランチフィルター。空のままにすると、フィルターは適用されません。

その他の設定

  • プロジェクト URL — リモート Azure DevOps サーバーと同期するためのプロジェクト URL。このフィールドは、オンプレミスの Azure DevOps インストールに推奨されます。空のままにすると、URL は VCS ルートフェッチ URL に基づいて構成されます。

JetBrains Space マージリクエスト

この機能は、元のリポジトリのソースブランチでマージリクエストを直接監視します。
同じソースブランチから複数のマージリクエストが送信された場合、TeamCity はビルド結果にこれらすべてのリクエストを表示します。ただし、フィルタリング基準に一致するオープンリクエストからのコミットのみがビルドの変更として表示されます。

JetBrains Space ホスティング型では、次のパラメーターを使用できます。

パラメーター

説明

接続

JetBrains Space への事前構成された接続を選択します。

ターゲットブランチ

ブランチフィルターを定義して、指定された基準に一致するブランチでのみマージ要求をモニターします。空のままにすると、フィルターは適用されません。

複数の並列ビルドを実行して、リクエストをマージする前に事前テストする場合、最善の解決策は次のとおりです。

  1. 複合ビルド構成を作成し、空のブランチ仕様を持つ JetBrains Space VCS ルートをそれに接続します。

  2. テストを使用した並列ビルドでスナップショットの依存関係を構成することにより、ビルドチェーンの最後に複合ビルド構成を追加します。

  3. チェーンの各ビルド構成にプルリクエスト機能を追加して、すべてのビルドがマージリクエストブランチの変更を検出できるようにします。ビルド構成テンプレートですべての設定を事前構成してから、それに基づいてこれらのビルド構成を作成できます。

  4. 複合ビルド構成設定の場合:

    • VCS トリガーを追加して、マージ要求ブランチで検出された変更に基づいてビルドを自動的に実行します。

    • ステータス発行者のコミット機能を追加して、ビルドステータスを JetBrains Space のコミット詳細に送信します。
      チェーンの他のビルド ( デプロイまたは統合テストビルドなど) のステータスを JetBrains Space に報告する場合は、対応するビルド構成にコミットステータスパブリッシャー機能を追加します。

その後、TeamCity は、JetBrains Space リポジトリに送信されたマージリクエストブランチの変更に基づいてビルドを自動的に実行し、Space のマージリクエストタイムラインにビルドステータスを公開します。

Space merge request timeline

JetBrains Space ブランチを未検証のマージリクエストから保護するために、リポジトリ設定で品質ゲートを構成することもできます。TeamCity ビルドを外部チェックとして設定した場合、JetBrains Space では、このリクエストのマージを許可する前に、マージリクエストのビルドが正常に終了する必要があります。

JetBrains Space マージリクエストの処理に関する既知の問題については、こちらを参照してください。

プルリクエストの定義済みビルドパラメーター

TeamCity は、有効化されたプルリクエスト機能を使用して、ビルドのプルリクエストに関する重要な情報を公開する複数の定義済みビルドパラメーターを提供します。

teamcity.pullRequest.number //pull request number teamcity.pullRequest.title //pull request title teamcity.pullRequest.source.branch //VCS name of the source branch; provided only if the source repository is the same as the target one teamcity.pullRequest.target.branch //VCS name of the target branch

これらのパラメーターは、ビルド構成の設定またはビルドスクリプトで使用できます。

プルリクエストワークフローの例

次の環境がセットアップされているとします。

  • パブリック GitHub リポジトリ web-app とデフォルトのブランチ master

  • TeamCity プロジェクト。

    • web-app リポジトリからのファイルを使用して Web アプリケーションをビルドする構成 web-app をビルドします。

組織(英語)のメンバーは、master ブランチにプルリクエストを送信してソースへの変更を提案し、これらの変更をマージする前に、TeamCity で自動的にビルドおよびテストしたいと考えています。
TeamCity は、master ブランチに送信された各プルリクエストを検出し、更新されたソースに基づいて Web アプリケーションを構築できます。

TeamCity で web-app ビルド構成の説明されたワークフローを構成するには、次のようにします。

  1. VCS ルートを追加するからビルド構成へ :

    • ビルド設定 | バージョン管理設定に移動し、VCS ルートを接続するをクリックしてください。

    • ルートパラメーターを設定します。

      • VCS の種類 : Git

      • VCS ルート名 : <一意のルート名>

      • URL を取得 : <GitHub_repository_URL>

      • デフォルトブランチ : 監視対象のブランチ。デフォルトでは、refs/heads/master ( 機能ブランチの詳細を読む)

      • ブランチ仕様 : 追加のブランチを監視するためのフィルター (たとえば、+:refs/heads/*)

      • web-app リポジトリへのアクセス権を持つ GitHub ユーザーの認証パラメーター

    • 接続をテストし、成功したら作成をクリックします。

  2. プルリクエスト ビルド機能を追加するからビルド構成へ :

    • ビルド設定 | 機能を構築するに移動し、ビルド機能を追加をクリックしてください。

    • 関数型パラメーターを構成します。

      • VCS ルート : ステップ 1 で作成された VCS ルート

      • VCS ホスティングタイプ : GitHub

      • 認証タイプ : VCS ルート資格情報を使用するか、アクセストークンを選択して代わりに GitHub トークンを使用します

      • プルリクエストフィルタリング :

        • 作成者による : 同じ組織のメンバー

        • ターゲットブランチ : 空のままにして、フィルターを適用せず、リポジトリ内のすべての新しいプル要求をモニターするか、ターゲットブランチを明示的に指定します (この例では、master)

    • 接続をテストし、成功したら保存をクリックします。

  3. ビルド構成に VCS トリガーを追加します。

以上です ! これで、GitHub 組織のメンバーが master ブランチにプルリクエストを送信するたびに、TeamCity は次のように動作します。

  1. master ブランチに送信されたプル要求を検出します。

  2. web-app ビルド構成を実行します。定義済みのビルド手順に従って、ソースを収集し、アプリをビルドしてテストします。

  3. ビルド構成概要ページで処理されたプル要求に関する情報を表示します。プルリクエストのステータスをすぐに確認でき(1)、そのステータスに関する情報をリフレッシュできます(2)。

    Pull Request information in Build Overview

プロのヒント

セットアップをさらに自動化できるため、TeamCity:

  • ステータス発行者のコミットビルド機能を使用して、ビルドが完了した後、ビルドステータスを GitHub に送り返します。

  • ビルドが正常に終了した場合、自動マージビルド機能を使用して GitHub のプルリクエストをマージします。

  • プルリクエストでビルドチェーン全体を実行する場合は、チェーンの各ビルド構成にプルリクエスト機能を追加することを忘れないでください。この手順を簡略化するために、ビルド構成テンプレートにすべてを設定し、それに基づいてこれらのビルド構成を作成できます。

トラブルシューティング

TeamCity は、プルリクエストビルド機能に関連するイベントを teamcity-pull-requests.log ファイルに書き込みます。「debug-pull-requests」プリセットを適用して、DEBUG レベルのイベントをこのログに含めます。

関連ページ:

ビルド機能を追加する

ビルド機能は、ビルド構成に追加して、実行中のビルドやビルド結果のレポートに影響を与えることができる機能の一部です。TeamCity ビルドの特徴:TeamCity には、構成に追加できる次のビルド機能が付属しています。AssemblyInfo パッチャー AssemblyInfo.cs ファイルに手動でパッチを適用することなく、アセンブリにビルド番号を自動的に設定できます。詳細 ... 自動マージ必要なブランチのビルドを追跡し、ビルドが構成された条件を満たした場合 (たとえば、ビルドが成功した場合...

ビルド結果ページ

TeamCity では、ビルドに関するすべての情報は、キューに入れられているか、実行中であるか、終了しているかにかかわらず、ビルド結果ページに蓄積されます。このページには、ビルド構成ホームページから、ホームモードで参照しているときに、ビルド番号またはビルドステータスがリンクとして表示される TeamCity UI のさまざまな場所からアクセスできます。一部のデータは、ビルドが終了した後にのみアクセスできます。変更、パラメーター、依存関係などの詳細は、キューで待機しているビルドにも適用できます。こ...

VCS トリガーの設定

VCS トリガーは、TeamCity が構成済みの VCS ルートの新しい変更を検出するたびに新しいビルドを自動的に開始し、保留中の変更の変更を表示します。複数の VCS トリガーをビルド構成に追加できます。ビルド構成に保留中の変更があると、デフォルト設定の新しい VCS トリガーがビルドをトリガーします。構成されている場合、VCS コミットフックを尊重する VCS ルートの変更間隔のチェックに従って、バージョン管理が変更についてポーリングされます。チェックアウトルールに一致した変更のみが保留中と...

サービスメッセージ

サービスメッセージは、ビルドスクリプトから TeamCity サーバーにビルドに関するコマンド / 情報を渡す特別に作成されたテキストです。TeamCity、それらはビルドの標準出力ストリームに書き込まれる必要があり、ビルドステップから出力またはエコーされますによって処理されます。例:echo ##teamcity[<messageName> 'value']echo "##teamcity[<messageName> 'value']"Write-Host "##tea...

バージョン管理でのプロジェクト設定の保存

TeamCity を使用すると、プロジェクト設定をバージョン管理リポジトリ(VCS)と同期できます。サポートされている VCS は、Git、Mercurial、Perforce、Subversion、Azure DevOps Server(以前の TFS)です。プロジェクト設定を XML 形式または Kotlin 言語で保存し、Kotlin ベースの DSL を使用してプログラムで設定を定義できます。バージョン設定は、TeamCity データディレクトリと同じ形式で、VCS リポジトリのルートにある...

信頼できないビルド

信頼できないビルドセクションでは、外部ユーザーが作成した悪意のあるコードが TeamCity で実行されるのを防ぐことを目的とした変更検証プロセスを設定できます。共通情報:VCS ルートが、外部ユーザーがプルリクエストを介して変更をコミットできる設定になっているパブリックリポジトリをターゲットにしている場合、新しい変更が検出されると VCS トリガーが自動的に新しいビルドを開始し、次のいずれかが当てはまる場合、TeamCity は悪意のあるコードを実行できます。プルリクエスト機能が有効になってお...