Webhookのトラブルシューティング

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

GitLabのWebhookに関する一般的な問題をトラブルシューティングして解決します。

Webhookをデバッグする

GitLab Webhookをデバッグし、ペイロードをキャプチャするには、次の方法を使用します:

WebhookイベントとJSONペイロードの詳細については、webhook eventsを参照してください。

公開のWebhook検査ツールを使用する

公開ツールを使用してWebhookペイロードを検査およびテストします。これらのツールは、HTTPリクエストのキャッチオールエンドポイントを提供し、200 OKステータスコードで応答します。

公開ツールを使用する際は、機密データが外部サービスに送信される可能性があるため、注意してください。テストトークンを使用し、誤って第三者に送信されたシークレットをローテーションしてください。プライバシーを強化するために、private Webhookレシーバーを作成します。

公開のWebhook検査ツールには、次のものが含まれます:

Beeceptor: 一時的なHTTPSエンドポイントを作成し、受信ペイロードを検査します。

Webhook.site: 受信ペイロードをレビューします。
Webhook Tester: 受信ペイロードを検査およびデバッグします。

GitLab Development Kit (GDK)を使用する

より安全な開発環境のために、GitLab Webhookをローカルで操作するには、GitLab Development Kit (GDK)を使用します。GDKを使用して、ローカルのGitLabインスタンスからマシンのWebhookレシーバーにWebhookを送信します。

このアプローチを使用するには、GDKをインストールして設定します。

プライベートWebhookレシーバーを作成する

公開WebhookレシーバーにWebhookペイロードを送信できない場合は、独自のプライベートWebhookレシーバーを作成します。

前提条件:

システムにRubyがインストールされています。

プライベートWebhookレシーバーを作成するには:

このスクリプトをprint_http_body.rbとして保存します:

require 'webrick'

server = WEBrick::HTTPServer.new(:Port => ARGV.first)
server.mount_proc '/' do |req, res|
  puts req.body
end

trap 'INT' do
  server.shutdown
end
server.start

未使用のポート (例: 8000) を選択し、スクリプトを開始します:
```
ruby print_http_body.rb 8000
```
GitLabで、WebhookをレシーバーのURL (例: http://receiver.example.com:8000/) で設定します。

Testを選択します。次のような出力が表示されます:

{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}
example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0
- -> /

このレシーバーを追加するには、ローカルネットワークへのリクエストを許可する必要がある場合があります。

SSL証明書検証エラーを解決する

SSL検証が有効になっている場合、GitLabはWebhookエンドポイントのSSL証明書の検証に失敗し、次のエラーが発生する可能性があります:

unable to get local issuer certificate

このエラーは通常、ルート証明書がCAcert.orgによって決定された信頼できる認証局によって発行されていない場合に発生します。

この問題を解決するには、次の手順に従います:

特定のエラーを特定するには、SSL Checkerを使用します。
検証失敗の一般的な原因である、中間証明書の欠落を確認します。

Webhookがトリガーされない

Webhookがトリガーされない場合は、以下を確認します:

そのWebhookが自動的に無効化されていない。
GitLabインスタンスがSilent Modeではない。
Push event activities limitとPush event hooks limit設定が、管理者エリアで0より大きい値に設定されている。

エラー: `Webhook rate limit exceeded`

Webhookはレート制限のために失敗する可能性があります。GitLab.comは、トップレベルネームスペースごとに、毎分のWebhook呼び出しの総数を制限します。詳細については、レート制限を参照してください。

レート制限が問題であるかどうかを確認するには:

メッセージWebhook rate limit exceededについて、GitLabログを確認してください。
Webhookをトリガーするイベントの数を減らすか、GitLabサポートに連絡して、レート制限の要件について話し合ってください。

引用符なしのプレースホルダーを持つカスタムWebhookテンプレートは保存できません

GitLab 18.8から18.10では、引用符なしのペイロードフィールドを持つカスタムWebhookテンプレートを保存できません。この問題はGitLab 18.11で解決されました。回避策として、フィールドを引用符で囲むか、GitLab 18.11以降にアップグレードしてください。たとえば、{"value": {{id}}}は{"value": "{{id}}"}になります。

引用符で囲まれたフィールドは、数値ではなく文字列値を生成します。これがWebhookと互換性がなく、変更を加える必要がある場合は、アップグレードをお勧めします。