gitlab-webhook

Webhook スキル

glab api の raw エンドポイント呼び出しを使用した GitLab の Webhook 管理です。

クイックリファレンス

操作	コマンドパターン	リスク
Webhook の一覧表示	glab api projects/:id/hooks	-
Webhook の取得	glab api projects/:id/hooks/:hook_id	-
Webhook の作成	glab api projects/:id/hooks -X POST -f ...	⚠️
Webhook の更新	glab api projects/:id/hooks/:hook_id -X PUT -f ...	⚠️
Webhook の削除	glab api projects/:id/hooks/:hook_id -X DELETE	⚠️⚠️
Webhook のテスト	glab api projects/:id/hooks/:hook_id/test/:trigger -X POST	⚠️
グループフックの一覧表示	glab api groups/:id/hooks	-

リスクの凡例：- 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危険

このスキルを使う場合

必ず使う場合：

• ユーザーが「webhook」「hook」「web hook」と言及した場合
• ユーザーが GitLab と外部サービスとの連携を希望している場合
• ユーザーが「notification」「callback」「trigger URL」と言及した場合
• ユーザーが CI/CD 連携または Slack 通知の設定を希望している場合

使わない場合：

• ユーザーが組み込み連携の設定を希望している場合（プロジェクト設定を使用）
• ユーザーが CI/CD パイプラインの管理を希望している場合（gitlab-ci を使用）
• ユーザーがシステムフックを希望している場合（管理者アクセスが必要）

API の前提条件

必須のトークンスコープ： api

権限：

• Webhook の表示：Maintainer 以上
• Webhook の管理：Maintainer 以上

Webhook イベント

イベント	フラグ	説明
プッシュ	push_events	リポジトリへのコードのプッシュ
タグ	tag_push_events	タグの作成／削除
マージリクエスト	merge_requests_events	MR の作成／更新／マージ
イシュー	issues_events	イシューの作成／更新／クローズ
ノート	note_events	MR／イシュー／コミットへのコメント
機密ノート	confidential_note_events	機密コメント
ジョブ	job_events	CI ジョブのステータス変更
パイプライン	pipeline_events	パイプラインのステータス変更
デプロイ	deployment_events	デプロイのステータス変更
Wiki	wiki_page_events	Wiki ページの作成／更新
リリース	releases_events	リリースの作成

利用可能なコマンド

Webhook の一覧表示

# List project webhooks
glab api projects/123/hooks --method GET

# List with pagination
glab api projects/123/hooks --paginate

# List group webhooks (Premium)
glab api groups/456/hooks --method GET

# Using project path
glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/hooks"

Webhook の詳細取得

# Get specific webhook
glab api projects/123/hooks/789 --method GET

Webhook の作成

# Basic webhook for push events
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=true

# Webhook for MR and pipeline events
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=false \
  -f merge_requests_events=true \
  -f pipeline_events=true

# Webhook with secret token
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=true \
  -f token="my-secret-token" \
  -f enable_ssl_verification=true

# Full-featured webhook
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=true \
  -f tag_push_events=true \
  -f merge_requests_events=true \
  -f issues_events=true \
  -f note_events=true \
  -f pipeline_events=true \
  -f job_events=true \
  -f token="secret" \
  -f enable_ssl_verification=true

# Webhook for specific branches only
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=true \
  -f push_events_branch_filter="main"

Webhook の更新

# Update URL
glab api projects/123/hooks/789 --method PUT \
  -f url="https://new-url.com/webhook"

# Enable additional events
glab api projects/123/hooks/789 --method PUT \
  -f pipeline_events=true \
  -f job_events=true

# Disable event
glab api projects/123/hooks/789 --method PUT \
  -f push_events=false

# Update secret token
glab api projects/123/hooks/789 --method PUT \
  -f token="new-secret-token"

# Change SSL verification
glab api projects/123/hooks/789 --method PUT \
  -f enable_ssl_verification=false

Webhook の削除

# Delete webhook
glab api projects/123/hooks/789 --method DELETE

Webhook のテスト

# Test push event
glab api projects/123/hooks/789/test/push_events --method POST

# Test MR event
glab api projects/123/hooks/789/test/merge_requests_events --method POST

# Test tag push event
glab api projects/123/hooks/789/test/tag_push_events --method POST

# Test note event
glab api projects/123/hooks/789/test/note_events --method POST

# Test issues event
glab api projects/123/hooks/789/test/issues_events --method POST

Webhook の設定オプション

オプション	型	説明
url	string	Webhook エンドポイントの URL（必須）
token	string	検証用のシークレットトークン
push_events	boolean	プッシュ時にトリガー
push_events_branch_filter	string	プッシュイベント用のブランチフィルター
tag_push_events	boolean	タグのプッシュ時にトリガー
merge_requests_events	boolean	MR イベント時にトリガー
issues_events	boolean	イシューイベント時にトリガー
confidential_issues_events	boolean	機密イシュー時にトリガー
note_events	boolean	コメント時にトリガー
confidential_note_events	boolean	機密ノート時にトリガー
pipeline_events	boolean	パイプラインイベント時にトリガー
job_events	boolean	ジョブイベント時にトリガー
deployment_events	boolean	デプロイ時にトリガー
wiki_page_events	boolean	Wiki の変更時にトリガー
releases_events	boolean	リリース時にトリガー
enable_ssl_verification	boolean	SSL 証明書を検証

よくあるワークフロー

ワークフロー 1：Slack 通知を設定する

# Create webhook for Slack
glab api projects/123/hooks --method POST \
  -f url="https://hooks.slack.com/services/T00/B00/XXX" \
  -f push_events=true \
  -f merge_requests_events=true \
  -f pipeline_events=true \
  -f enable_ssl_verification=true

ワークフロー 2：CI トリガーを設定する

# Webhook to trigger external CI
glab api projects/123/hooks --method POST \
  -f url="https://ci.example.com/trigger" \
  -f push_events=true \
  -f tag_push_events=true \
  -f token="ci-trigger-token" \
  -f push_events_branch_filter="main"

ワークフロー 3：すべての Webhook を監査する

# List all webhooks with details
glab api projects/123/hooks --paginate | \
  jq -r '.[] | "ID: \(.id)\n  URL: \(.url)\n  Events: push=\(.push_events), mr=\(.merge_requests_events), pipeline=\(.pipeline_events)\n  SSL: \(.enable_ssl_verification)\n"'

ワークフロー 4：Webhook の URL を新しい URL に移行する

# 1. Get current webhook config
glab api projects/123/hooks/789 | jq

# 2. Update URL
glab api projects/123/hooks/789 --method PUT \
  -f url="https://new-service.example.com/webhook"

# 3. Test the webhook
glab api projects/123/hooks/789/test/push_events --method POST

ワークフロー 5：デプロイ通知を設定する

# Webhook for deployment events only
glab api projects/123/hooks --method POST \
  -f url="https://deploy-tracker.example.com/webhook" \
  -f push_events=false \
  -f deployment_events=true \
  -f token="deploy-secret"

ワークフロー 6：必須でないイベントをすべて無効にする

hook_id=789

# Keep only push and MR events
glab api projects/123/hooks/$hook_id --method PUT \
  -f push_events=true \
  -f merge_requests_events=true \
  -f tag_push_events=false \
  -f issues_events=false \
  -f note_events=false \
  -f job_events=false \
  -f pipeline_events=false

Webhook ペイロード

GitLab はイベントデータを含む JSON ペイロードを送信します。主なフィールド：

プッシュイベントのペイロード

{
  "object_kind": "push",
  "ref": "refs/heads/main",
  "before": "abc123...",
  "after": "def456...",
  "commits": [...],
  "project": {...}
}

MR イベントのペイロード

{
  "object_kind": "merge_request",
  "event_type": "merge_request",
  "object_attributes": {
    "iid": 1,
    "title": "...",
    "state": "opened",
    "action": "open"
  }
}

Webhook の検証

シークレットトークンを使って Webhook が正当なものであることを検証します：

# In your webhook handler, verify the X-Gitlab-Token header
# matches the token you configured

トラブルシューティング

問題	原因	解決策
Webhook が発火しない	イベントが有効になっていない	イベントフラグを確認してください
403 Forbidden	メンテナーではない	Maintainer 以上のロールが必要です
SSL の検証に失敗した	証明書が無効	enable_ssl_verification=false を使用するか、証明書を修正してください
Webhook URL に到達できない	ネットワーク／ファイアウォールの問題	GitLab から URL にアクセスできることを確認してください
テストでエラーが返される	エンドポイントのエラー	Webhook ハンドラーのログを確認してください
リクエストが多すぎる	Webhook のループ	ハンドラーがイベントを発生させないことを確認してください

ベストプラクティス

1. HTTPS を使用する：Webhook には常に安全な URL を使用してください
2. シークレットトークンを設定する：シークレットトークンを使って Webhook を検証してください
3. 必要なイベントのみを有効にする：不要な通知と処理を減らしてください
4. 失敗を適切に処理する：GitLab は配信に失敗すると再試行します
5. Webhook の状態を監視する：GitLab UI で最近の配信を確認してください
6. ブランチフィルターを使用する：プッシュイベントを関連するブランチに限定してください

関連ドキュメント

• API ヘルパー
• セーフガード
• クイックリファレンス
• GitLab Webhooks API