正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

外部ステータスチェック

  • プラン: Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

ステータスチェックは、外部要件のステータスをリクエストする外部システムへのAPIコールです。

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

このインテグレーションにより、ServiceNowなどのサードパーティワークフローツール、または任意のカスタムツールとインテグレーションできます。サードパーティツールは、関連するステータスで応答します。このステータスは、マージリクエスト内のブロックしないウィジェットとして表示され、マージリクエストレベル自体で、このステータスをマージリクエストの作成者またはレビュアーに表面化します。

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

ステータスチェックは、保留中の状態で2分以上経過すると失敗します。

アクセス許可

外部ステータスチェックの応答は、以下によって表示できます:

  • プロジェクトで少なくともレポーターのロールを持つユーザー
  • プロジェクトの表示レベルが内部のときにマージリクエストを表示できる認証済みユーザー

つまり、内部プロジェクトがある場合、マージリクエストにアクセスできるログイン済みのユーザーは、外部ステータスチェックの応答を表示できます。

ユースケース、機能の検出、および開発タイムラインの詳細については、epic 3869を参照してください。

すべてのステータスチェックが完了した場合を除き、マージリクエストのマージをブロックします

デフォルトでは、プロジェクトのマージリクエストは、外部ステータスチェックが失敗した場合でもマージできます。外部チェックが失敗した場合にマージリクエストのマージをブロックするには、次のようにします:

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
  2. 設定 > マージリクエストを選択します。
  3. ステータスチェックが完了する必要がありますチェックボックスを選択します。
  4. 変更を保存を選択します。

ライフサイクル

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

  • マージリクエストが更新、クローズ、再オープン、承認、未承認、またはマージされた場合。
  • コードがマージリクエストのソースブランチにプッシュされた場合。
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: Workflow for external status checks
    accDescr: Merge request sends payload to external service and receives status check response

    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. 設定 > マージリクエストを選択します。
  3. 下にスクロールして、ステータスチェックを表示します。このリストには、サービス名、API URL、対象ブランチ、およびHMAC認証ステータスが表示されます。

ステータスチェックリスト

ブランチルールの設定から、ステータスチェックサービスのリストを表示することもできます。

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

ステータスチェックサービスを追加する

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

ステータスチェックの作成フォーム

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

ステータスチェックは、すべての新しいマージリクエストに適用されますが、既存のマージリクエストには遡って適用されません。

ステータスチェックサービスを更新する

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

ステータスチェックの更新フォーム

HMAC共有シークレットの値は表示または変更できません。共有シークレットを変更するには、共有シークレットの新しい値を使用して、外部ステータスチェックを削除して再作成します。

ステータスチェックを更新するには、フォームの値を変更し、ステータスチェックを更新を選択します。

ステータスチェックの更新は、すべての新しいマージリクエストに適用されますが、既存のマージリクエストには遡って適用されません。

フォームの値

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

サービス名

この名前には任意の英数字を使用でき、必ず設定する必要があります。名前はプロジェクトで必ず一意でなければなりません。名前はプロジェクトで必ず一意でなければなりません。

チェックするAPI

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

ターゲットブランチ

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

ステータスチェックブランチセレクター

ブランチのリストは、プロジェクトの保護ブランチから入力されたものです。

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

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

HMAC共有シークレット

HMAC認証は、リクエストの改ざんを防ぎ、正当なソースからのものであることを保証します。

ステータスチェックサービスを削除する

ステータスチェックサブセクション]で、削除するステータスチェックの横にある削除（ remove ）を選択します。次に、Remove status check?（ステータスチェックを削除しますか?）モーダルが表示されます。

ステータスチェックの削除モーダル

ステータスチェックの削除を完了するには、Remove status check（ステータスチェックの削除）ボタンを選択する必要があります。これにより、ステータスチェックが完全に削除され、回復できません。

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

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

  • 保留中（ status-neutral ）、GitLabが外部ステータスチェックからの応答を待機している間。
  • GitLabが外部ステータスチェックから応答を受信すると、成功（ status-success ）または失敗（ status-failed ）

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

失敗したステータスチェックを再試行するには、次のようにします:

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
  2. コード > マージリクエストを選択して、マージリクエストを見つけます。
  3. マージリクエストレポートセクションまでスクロールし、ドロップダウンリストを展開して、外部ステータスチェックのリストを表示します。
  4. 失敗した外部ステータスチェック行で、再試行（ retry ）を選択します。ステータスチェックが保留中の状態に戻されます。

組織には、外部ステータスチェックが合格しない場合にマージリクエストのマージを許可しないポリシーがある場合があります。ただし、ウィジェットの詳細は、情報提供のみを目的としています。

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

トラブルシューティング

値の重複エラー

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

プロジェクトごとに、ステータスチェックは名前またはAPI URLを1回のみ使用できます。これらのエラーは、ステータスチェックの名前またはAPI URLが、このプロジェクトのステータスチェックですでに使用されていることを意味します。

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

無効なURLエラー

Please provide a valid URL

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

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

ブランチ取得APIから予期しない応答を受信しました。推奨どおり、フォームを閉じて再度開くか、ページを更新する必要があります。このエラーは一時的なものですが、解決しない場合は、GitLabステータスページを確認して、より広範な停止が発生していないか確認してください。

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

Failed to load status checks

外部ステータスチェックAPIから予期しない応答を受信しました。以下を行う必要があります:

  • このエラーが一時的なものである場合に備えて、ページを更新します。
  • 問題が解決しない場合は、GitLabステータスページを確認して、より広範な停止が発生していないか確認してください。