プル要求の状態を使用して pull request ワークフローをカスタマイズおよび拡張する

Azure DevOps Services |Azure DevOps Server 2022 および Azure DevOps Server 2019

プル要求 は、コード レビューを容易にし、リポジトリ内のコード移動を管理するための優れたツールです。 ブランチ ポリシーでは、 すべてのコード変更に対して実行する必要がある要件を確立することで、プル要求プロセス中にコード品質が適用されます。 これらのポリシーを使用すると、チームはコードのレビューと自動ビルドの実行に関連する多くのベスト プラクティスを適用できますが、多くのチームには、コードで実行するための追加の要件と検証があります。 これらの個々のニーズとカスタムのニーズに対応するために、Azure Repos ではプル要求の状態が提供されます。 プル要求の状態は PR ワークフローに統合され、単純な成功/失敗の種類の情報を pull request に関連付けることで、外部サービスがコード変更でプログラムによってサインオフできるようにします。 必要に応じて、外部サービスが変更を承認するまで、プル要求をブロックできます。

前提条件

PR ワークフローへの統合には、いくつかの異なる概念が含まれます。

• プル要求の状態 - サービスが成功/失敗情報をプル要求に関連付ける方法を提供します。
• 状態ポリシー - プル要求の状態が成功を示すまで、プル要求の完了をブロックするメカニズムを提供します。
• カスタム アクション - Azure DevOps Services 拡張機能を使用して状態メニューを拡張する方法を提供します。

このトピックでは、プル要求の状態と、その状態を使用して PR ワークフローに統合する方法について説明します。

プルリクエストの状態

プル要求の状態は、 サービスが Status API を使用して単純な成功/失敗の種類の情報をプル要求に関連付ける方法を提供します。 状態は、次の 4 つの重要なデータで構成されます。

• State。 次のいずれかの定義済みの状態: succeeded、 failed、 pending、 notSet、 notApplicable、または error。
• 説明。 エンド ユーザーの状態を説明する文字列。
• [コンテキスト]。 状態の名前 - 通常、状態を転記するエンティティを記述します。
• URL。 ユーザーが状態に固有の詳細情報を取得できるリンク。

基本的に、状態は、ユーザーまたはサービスが pull request に関する評価を投稿し、次のような質問に対する回答を提供する方法です。

• 変更は要件を満たしましたか?
• 要件を満たすために必要な操作の詳細については、どこで確認できますか?

例を見てみましょう。 プロジェクト内のすべてのコード変更をビルドするために必要な CI サービス について考えてみましょう。 そのサービスがプル要求の変更を評価するときは、ビルドとテストの結果をポストバックする必要があります。 ビルドに合格した変更の場合、次のような状態が PR にポストされる可能性があります。

{
    "state": "succeeded",
    "description": "CI build succeeded",
    "context": {
        "name": "my-ci-system",
        "genre": "continuous-integration"
    },
    "targetUrl": "http://contoso.com/CI/builds/1"
}

この状態は、PR 詳細ビューでエンド ユーザーに表示されます。

• stateは、アイコン (succeededの緑色のチェック、failedの赤い X、pendingの時計、errorの場合は赤の ! ) を使用してユーザーに表示されます。
• アイコンの横に description が表示され、ツールヒントに context が表示されます。
• targetUrlが適用されると、説明が URL へのリンクとしてレンダリングされます。

状態の更新

サービスでは、追加のステータスを投稿することで、1 つの PR の PR ステータスを更新できます。一意の contextごとに最新の状態のみが表示されます。 複数の状態を投稿すると、ユーザーが期待値を管理するのに役立ちます。 たとえば、 pending 状態を投稿することは、システムがイベントを受信し、作業を開始していることをユーザーに確認する良い方法です。 次の例のような有益な description を使用すると、ユーザーがシステムの動作を理解するのにさらに役立ちます。

• "ビルドがキューに登録されました"
• "ビルドの進行中です"
• "ビルドが成功しました"

反復処理の状態

PR のソース ブランチが変更されると、最新の変更を追跡するための新しい "イテレーション" が作成されます。 コードの変更を評価するサービスは、PR のイテレーションごとに新しい状態を投稿する必要があります。 PR の特定のイテレーションに状態を投稿すると、評価されたコードにのみ状態が適用され、今後の更新は適用されません。

逆に、転記された状態がコードに関係なく PR 全体に適用される場合、イテレーションへの転記は不要である可能性があります。 たとえば、作成者 (変更できない PR プロパティ) が特定のグループに属していることを確認するには、1 回だけ評価する必要があり、イテレーションの状態は必要ありません。

状態ポリシーを構成するときに、イテレーションの状態が使用されている場合は、新しい変更がある場合は常にリセット状態にリセット条件を設定する必要があります。 これにより、最新のイテレーションの状態が succeeded になるまで、PR をマージできないことが保証されます。

イテレーションとプル要求での状態の投稿については、REST API の例を参照してください。

ステータスポリシー

状態のみを使用すると、外部サービスの詳細を PR エクスペリエンス内のユーザーに提供できます。 PR に関する情報の共有が必要な場合もありますが、要件が満たされるまで PR のマージをブロックする必要がある場合もあります。 インボックス ポリシーと同様に、 Status ポリシー は、要件が満たされるまで外部サービスが PR の完了をブロックする方法を提供します。 ポリシーが必須の場合、pull request を完了するにはポリシーに合格する必要があります。 ポリシーが省略可能な場合は情報のみであり、プル要求を完了するために succeeded の状態は必要ありません。

状態ポリシーは、他の ブランチ ポリシーと同様に構成されます。 新しいステータス ポリシーを追加するときは、ステータス ポリシーの 名前 と ジャンル を入力する必要があります。 ステータスが以前に転記されている場合は、リストから選択できます。新しいポリシーの場合は、ジャンル名/形式でポリシーの名前を入力できます。

状態ポリシーを指定する場合、このポリシーが通過するには、選択された名前と一致するcontextを持つsucceededの状態が存在する必要があります。

承認されたアカウントを選択して、ポリシーを承認する状態を投稿する権限を特定のアカウントに付与するように要求することもできます。

ポリシーの適用性

ポリシーの適用オプションは、プル要求が作成されるとすぐにこのポリシーを適用するか、または最初の状態がプル要求にポストされた後にのみポリシーを適用するかどうかを決定します。

1. 既定で適用 - ポリシーは、プル要求が作成されるとすぐに適用されます。 このオプションでは、 succeeded の状態がポストされるまで、プル要求の作成後にポリシーは渡されません。 PR は、ポリシー要件を削除する notApplicableの状態を投稿することで、ポリシーから除外されるマークを付けることができます。

2. 条件付き - ポリシーは、最初の状態がプル要求にポストされるまで適用されません。

これらのオプションを組み合わせて使用して、一連の動的ポリシーを作成できます。 PR が適用可能なポリシーの評価中に、最上位レベルの "オーケストレーション" ポリシーを既定で適用するように設定できます。 その後、追加の条件付きポリシーが適用されると判断されると (おそらく特定のビルド出力に基づいて)、状態を投稿して必須にすることができます。 このオーケストレーション ポリシーは、評価が完了したときに succeeded マークすることも、ポリシーが適用されていないことを PR に示すために notApplicable マークすることもできます。

カスタム アクション

サービスをトリガーして PR 状態を更新できる定義済みのサービス フック イベントに加えて、 Azure DevOps Services 拡張機能 を使用してエンド ユーザーにトリガー アクションを提供することで、状態メニューを拡張できます。 たとえば、状態がエンド ユーザーが再起動できるテストの実行に対応する場合、テストの実行をトリガーする状態メニューに [再起動 ] メニュー項目を表示できます。 状態メニューを追加するには、 コントリビューション モデルを使用する必要があります。 詳細については、 Azure DevOps 拡張機能のサンプルを参照してください。

次のステップ

PR Status API の詳細を確認し、ハウツー ガイドを確認してください。

• Node.jsを使用して pull request 状態サーバーを作成する
• Azure Functions を使用してカスタム ブランチ ポリシーを作成する
• 外部サービス のブランチ ポリシーを構成する