pull request の状態を使用して pull request ワークフローをカスタマイズして拡張する

[アーティクル]
04/05/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

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

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

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

このトピックでは、pull request の状態について、および PR ワークフローに統合するために pull request をどのように使用するかについて説明します。

pull request の状態

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

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

基本的に、状態は、ユーザーまたはサービスが pull request に関する評価を投稿し、次のような質問に回答する手段となります。

変更は要件を満たしていましたか?
要件を満たすために行う必要がある詳しい内容は、どこで確認できますか?

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

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

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

pull request の状態

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

状態の更新中

サービスでは、追加の状態を投稿して、1 つの PR の PR 状態を更新する場合があります。一意の context ごとに最新の状態のみが表示されます。複数の状態を投稿すると、ユーザーが予測を管理するのに役立ちます。たとえば、pending の状態を投稿すると、システムがイベントを受信していて、処理を開始していることをユーザーに知らせる適切な方法になります。次の例のような、情報を提供する description を利用して、ユーザーは、システムの動作状態をさらに詳しく把握できます。

[ビルドがキューに挿入されました]
[ビルドの進行中です]
[ビルドが正常に終了しました]

イテレーションの状態

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

Note

作成注の PR に 100,000 を超える変更されたファイルが含まれている場合、パフォーマンスと安定性の理由から、その PR ではイテレーションがサポートされません。つまり、このような PR に対する追加の変更は含まれますが、その変更に対して新しいイテレーションは作成されません。また、存在しないイテレーションの状態を作成しようとすると、エラーが返されます。

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

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

状態ポリシーの [条件のリセット]

イテレーションおよび pull request の状態を投稿する場合の REST API の例を参照してください。

状態ポリシー

状態を単独で使用する場合、外部サービスからの詳細を PR エクスペリエンス内でユーザーに提供できます。 PR に関する情報を共有するだけで十分な場合もありますが、要件が満たされるまで PR のマージをブロックすることが必要な場合もあります。インボックスポリシーと同様に、状態ポリシーは、要件が満たされるまで外部サービスが PR の完了をブロックする手段となります。このポリシーが必須の場合、pull request を完了するには、そのポリシーが合格となる必要があります。このポリシーが省略可能な場合は、情報を提供しているだけであり、pull request を完了するために succeeded 状態は必須ではありません。

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

状態ポリシー

状態ポリシーを指定する場合、このポリシーが合格となるには、context が選択した名前と一致している、succeeded の状態が存在する必要があります。

また、承認済みアカウントを選択して、ポリシーを承認する状態を投稿する権限を、特定のアカウントが持つように求めることもできます。

ポリシーの適用性

[ポリシーの適用性] オプションは、pull request が作成されるとすぐにこのポリシーが適用されるか、または最初の状態が pull request に投稿された後にのみポリシーが適用されるかを決定します。

ポリシーの適用性

[既定で適用] - ポリシーは、pull request が作成されるとすぐに適用されます。このオプションを選択すると、pull request の作成後、ポリシーは succeeded 状態が投稿されるまで合格となりません。ポリシーの要件を削除する notApplicable の状態を投稿すると、PR をポリシーの適用外とすることができます。
[条件付き] - 最初の状態が pull request に投稿されるまで、ポリシーは適用されません。

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

カスタムアクション

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

次のステップ

PR 状態 API の詳細を確認し、攻略ガイドをチェックアウトします。

pull request の状態を使用して pull request ワークフローをカスタマイズして拡張する