外部ステータスのチェック

ステータスチェックは、外部システムに対する API 呼び出しで、外部要件のステータスを要求します。

サードパーティのツールにマージリクエストデータを送信するステータスチェックを作成することができます。ユーザーがマージリクエストを作成、変更、クローズすると、GitLab は通知を送信します。ユーザーや自動ワークフローは、GitLabの外からマージリクエストのステータスを更新することができます。

このインテグレーションでは、ServiceNowのようなサードパーティのワークフローツールや、お好みのカスタムツールと統合することができます。サードパーティツールは関連するステータスを応答します。このステータスは、マージリクエスト内のノンブロッキングウィジェットとして表示され、マージリクエスト作成者やレビュアーにマージリクエストレベルでステータスを表示します。

個々のプロジェクトごとにマージリクエストステータスチェックを設定することができます。これらはプロジェクト間では共有されません。

ユースケース、フィーチャーディスカバリー、開発タイムラインの詳細については、エピック 3869 を参照してください。

すべてのステータスチェックに合格しない限り、マージリクエストのマージはブロックされます。

  • GitLab 15.5 でonly_allow_merge_if_all_status_checks_passed というフラグで導入されました。デフォルトでは無効です。
  • GitLab15.8でGitLab.comで有効に。
  • GitLab 15.9でセルフマネージドで有効になり、機能フラグが削除されました。

デフォルトでは、外部からのステータスチェックが失敗しても、プロジェクト内のマージリクエストはマージされます。外部チェックが失敗した場合にマージリクエストをブロックするには：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定 > マージリクエストを選択します。
  3. ステータスのチェックは成功する必要があります] チェックボックスを選択します。
  4. 変更を保存を選択します。

ライフサイクル

外部ステータスチェックには非同期ワークフローがあります。マージリクエストは、マージリクエスト Webhook ペイロードを外部サービスに送信します：

  • マージリクエストが変更されたとき。たとえば、タイトルや説明。
  • コードはマージリクエストのソースブランチにプッシュされます。
  • マージリクエストのディスカッションにコメントが追加されます。
sequenceDiagram Merge request->>+External service: Merge request payload External service-->>-Merge request: Status check response Note over External service,Merge request: Response includes SHA at HEAD

ペイロードを受信すると、外部サービスはREST API を使用してマージリクエストにレスポンスを投稿する前に、必要な処理を実行できます。

マージリクエストは、ソースブランチの現在のHEAD を参照しないレスポンスに対して409 Conflict エラーを返します。その結果、外部サービスが古いコミットを処理したり応答したりするのは安全です。

外部のステータスチェックには以下の状態があります：

  • pending - デフォルトの状態。外部サービスからのマージリクエストによる応答がありません。
  • passed - 外部サービスからの応答を受信し、承認者。
  • failed - 外部サービスからの応答を受信し、拒否しました。

GitLab の外部で何かが変更された場合、API を使って外部ステータスチェックのステータスを設定することができます。最初にマージリクエスト Webhook ペイロードが送信されるのを待つ必要はありません。

プロジェクトのステータスチェックを見る

各プロジェクトの設定内で、プロジェクトに追加されたステータスチェックサービスのリストを見ることができます：

  1. プロジェクトで、[設定] > [マージリクエスト]セクションに移動します。
  2. ステータスチェックまでスクロールダウンします。

Status checks list

このリストには、サービス名、API URL、対象のブランチが表示されます。また、ステータスチェックを作成、編集、削除するためのアクションも表示されます。

ステータスチェックサービスの追加または更新

ステータスチェックサービスの追加

ステータス・チェック] サブセクションで、[ステータス・チェックの追加] ボタンを選択します。ステータスチェックの追加フォームが表示されます。

Status checks create form

フォームに入力し、[ステータスチェックの追加] ボタンを選択すると、新しいステータスチェックが作成されます。

ステータスチェックサービスの更新

ステータス・チェック] サブセクションで、編集するステータス・チェックの横にある [編集] ボタンを選択します。ステータスチェックの更新フォームが表示されます。

Status checks update form

フォームの値を変更し、[ステータスチェックの更新] ボタンを選択すると、ステータスチェックが更新されます。

フォームの値

一般的なフォームエラーについては、以下のトラブルシューティングのセクションを参照してください。

サービス名

この名前は任意の英数字で、必ず設定してください。プロジェクト内でユニークな名前である必要があります。この名前はプロジェクト内で一意でなければなりません。

確認するAPI

このフィールドには URL が必要で、HTTP または HTTPs プロトコルのいずれかを使用する必要があります。転送中のマージリクエストデータを保護するために、HTTPsを使用することをお勧めします。URLは必ず設定し、プロジェクトで一意でなければなりません。

ターゲットブランチ

ステータスチェックを単一のブランチに制限したい場合は、このフィールドを使用して制限を設定できます。

Status checks branch selector

ブランチリストには、プロジェクトで保護されているブランチが入力されます。

ブランチのリストをスクロールすることもできますし、ブランチの数が多くて目的のブランチがすぐに表示されない場合は、検索ボックスを使うこともできます。検索ボックスで検索を開始するには、3文字の英数字を入力する必要があります。

ステータスチェックをすべてのマージリクエストに適用したい場合は、［すべてのブランチ］オプションを選択できます。

ステータスチェックサービスの削除

ステータスチェック] サブセクションで、削除するステータスチェックの横にある [削除…] ボタンを選択します。ステータスチェックの削除]モーダルが表示されます。

Status checks delete modal

ステータスチェックの削除を完了するには、[ステータスチェックの削除] ボタンを選択する必要があります。これにより、ステータスチェックは永久に削除され、復元できなくなります。

ステータスチェックウィジェット

  • GitLab 14.1 で導入されました。
  • GitLab 15.2でUIを更新しました。
  • GitLab 15.8 で、失敗した外部ステータスチェックを再試行する機能を追加しました。
  • GitLab 15.11で、保留中のステータスチェックがある場合に更新をポーリングするようにウィジェットを更新。

ステータスチェックウィジェットはマージリクエストに表示され、以下のステータスを表示します：

  • pending({status-neutral}), GitLabは外部のステータスチェックからの応答を待っています。
  • success({status-success})またはfailed({status-failed})、GitLabが外部のステータスチェックからのレスポンスを受け取った時。

保留中のステータスチェックがある場合、ウィジェットは成功か 失敗のレスポンスを受け取るまで数秒ごとに更新をポーリングします。

失敗したステータスチェックを再試行するには

  1. マージリクエストウィジェットを展開して、外部ステータスチェックのリストを表示します。
  2. 失敗した外部ステータス・チェック行で再試行（{retry}）を選択します。ステータス・チェックが保留状態に戻ります。

組織によっては、外部ステータス・チェックが通らなかった場合、マージ・リクエストをマージできないポリシーがあるかもしれません。しかし、ウィジェットの詳細は情報提供のみを目的としています。GitLab はステータスチェックに失敗したマージリクエストのマージを妨げません。外部ステータスチェックが失敗したときにマージがブロックされるようにするサポートは、エピック&8516 で提案されています。

note
GitLabは外部ステータスチェックが関連する外部サービスによって適切に処理されることを保証できません。

トラブルシューティング

重複値エラー 

Name is already taken
---
External API is already in use by another status check

プロジェクト単位で、ステータスチェックは名前またはAPI URLを一度しか使用できません。これらのエラーは、ステータスチェック名またはAPI URLのいずれかが、このプロジェクトのステータスチェックですでに使用されていることを意味します。

現在のステータスチェックで別の値を選択するか、既存のステータスチェックの値を更新する必要があります。

無効なURLエラー 

Please provide a valid URL

チェックするAPI]フィールドでは、提供されたURLがHTTPまたはHTTPsプロトコルのいずれかを使用する必要があります。この要件を満たすようにフィールドの値を更新する必要があります。

Unable to fetch branches list, please close the form and try again

ブランチ検索APIから予期しない応答を受け取りました。ページを更新してください。このエラーは一時的なものであるはずですが、もしこのエラーが続くようであれば、GitLab のステータスページでより広範囲で障害が発生していないか確認してください。

ステータスチェックの読み込みに失敗しました 

Failed to load status checks

外部ステータス・チェック API から予期しない応答を受け取りました。次のようにしてください：

  • このエラーが一時的なものである場合に備えて、Pagesを更新してください。
  • 問題が解決しない場合は、GitLabのステータスページをチェックして、障害が拡大しているかどうかを確認してください。