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

外部ステータスチェック

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

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

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

このインテグレーションを使用すると、ServiceNowなどのサードパーティのワークフローツール、または選択したカスタムツールと統合できます。サードパーティツールは、関連するステータスで応答します。このステータスは、マージリクエスト内に非ブロック型のウィジェットとして表示され、マージリクエストレベルでマージリクエストの作成者またはレビュアーにこのステータスを提示します。

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

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

アクセス権限

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

  • プロジェクトでレポーター、デベロッパー、メンテナー、またはオーナーロールを持つユーザー
  • プロジェクトが内部表示レベルの場合にマージリクエストを表示できる認証済みユーザー

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

ユースケース、機能の発見、開発タイムラインに関する詳細については、エピック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が外部ステータスチェックからの応答を待機している間。
  • 成功 ( status-success ) または失敗 ( status-failed )、GitLabが外部ステータスチェックからの応答を受信した場合。

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

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

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

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

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から予期せぬ応答が受信されました。以下のことを行う必要があります:

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