gitlab-protected-branch

保護ブランチスキル

glab api の生のエンドポイント呼び出しを使用した GitLab のブランチ保護管理です。

クイックリファレンス

操作	コマンドパターン	リスク
保護ブランチ一覧	glab api projects/:id/protected_branches	-
保護設定の取得	glab api projects/:id/protected_branches/:name	-
ブランチの保護	glab api projects/:id/protected_branches -X POST -f ...	⚠️
保護設定の更新	glab api projects/:id/protected_branches/:name -X PATCH -f ...	⚠️
ブランチの保護解除	glab api projects/:id/protected_branches/:name -X DELETE	⚠️⚠️

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

このスキルを使用する場合

必ず使用する場合：

• ユーザーが「ブランチを保護」「ブランチ保護」「保護ブランチ」に言及した場合
• ユーザーがブランチへのプッシュ／マージを許可するユーザーを制限したい場合
• ユーザーが「フォースプッシュ」「コードオーナー」「マージアクセス」に言及した場合
• ユーザーが main／release ブランチのセキュリティを設定したい場合

使用しない場合：

• ユーザーがブランチを作成／削除したい場合（git または gitlab-repo を使用）
• ユーザーがマージリクエストの承認を管理したい場合（別の API を使用）
• ユーザーがブランチの CI/CD を設定したい場合（gitlab-ci を使用）

API の前提条件

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

権限：

• 保護ブランチの表示：Developer 以上
• 保護ブランチの管理：Maintainer 以上

Premium の機能：

• コードオーナーの承認：GitLab Premium
• 複数のアクセスレベル：GitLab Premium

アクセスレベル

レベル	値	説明
アクセスなし	0	誰も操作を実行できません
Developer	30	Developer 以上
Maintainer	40	Maintainer 以上
Admin	60	インスタンス管理者のみ

使用可能なコマンド

保護ブランチの一覧表示

# List all protected branches
glab api projects/123/protected_branches --method GET

# With pagination
glab api projects/123/protected_branches --paginate

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

保護設定の詳細を取得

# Get protection for specific branch
glab api projects/123/protected_branches/main --method GET

# Branch with special characters (URL-encode)
glab api "projects/123/protected_branches/$(echo 'release/1.0' | jq -Rr @uri)"

# Branch with wildcard pattern
glab api "projects/123/protected_branches/$(echo 'feature/*' | jq -Rr @uri)"

ブランチを保護

# Basic protection (maintainers push, developers merge)
glab api projects/123/protected_branches --method POST \
  -f name="main" \
  -f push_access_level=40 \
  -f merge_access_level=30

# Strict protection (only maintainers)
glab api projects/123/protected_branches --method POST \
  -f name="main" \
  -f push_access_level=40 \
  -f merge_access_level=40 \
  -f allow_force_push=false

# With code owner approval (Premium)
glab api projects/123/protected_branches --method POST \
  -f name="main" \
  -f push_access_level=40 \
  -f merge_access_level=30 \
  -f code_owner_approval_required=true

# Protect wildcard pattern
glab api projects/123/protected_branches --method POST \
  -f name="release/*" \
  -f push_access_level=40 \
  -f merge_access_level=40

# Allow developers to push, anyone to merge
glab api projects/123/protected_branches --method POST \
  -f name="develop" \
  -f push_access_level=30 \
  -f merge_access_level=30 \
  -f allow_force_push=false

# No direct push (only through MR)
glab api projects/123/protected_branches --method POST \
  -f name="main" \
  -f push_access_level=0 \
  -f merge_access_level=30

保護設定を更新

# Change merge access level
glab api projects/123/protected_branches/main --method PATCH \
  -f merge_access_level=40

# Enable code owner approval (Premium)
glab api projects/123/protected_branches/main --method PATCH \
  -f code_owner_approval_required=true

# Allow force push (not recommended for main)
glab api projects/123/protected_branches/feature%2F* --method PATCH \
  -f allow_force_push=true

ブランチの保護を解除

警告： この操作により、ブランチの保護がすべて解除されます！

# Unprotect branch
glab api projects/123/protected_branches/main --method DELETE

# Unprotect wildcard pattern (URL-encode)
glab api "projects/123/protected_branches/$(echo 'feature/*' | jq -Rr @uri)" --method DELETE

保護オプション

オプション	型	説明
name	string	ブランチ名またはワイルドカードパターン
push_access_level	integer	プッシュできるユーザー（0、30、40、60）
merge_access_level	integer	MR をマージできるユーザー（0、30、40、60）
unprotect_access_level	integer	保護を解除できるユーザー（40、60）
allow_force_push	boolean	ブランチへのフォースプッシュを許可
code_owner_approval_required	boolean	コードオーナーの承認を必須にする（Premium）

ワイルドカードパターン

パターン	一致するブランチ
*	すべてのブランチ
feature/*	feature/login、feature/signup など
release/*	release/1.0、release/2.0 など
hotfix/*	hotfix/bug-123 など
*-stable	1.0-stable、2.0-stable など

よく使うワークフロー

ワークフロー 1：標準的なブランチ保護

# Protect main branch
glab api projects/123/protected_branches --method POST \
  -f name="main" \
  -f push_access_level=40 \
  -f merge_access_level=30 \
  -f allow_force_push=false

# Protect develop branch
glab api projects/123/protected_branches --method POST \
  -f name="develop" \
  -f push_access_level=30 \
  -f merge_access_level=30 \
  -f allow_force_push=false

# Protect release branches
glab api projects/123/protected_branches --method POST \
  -f name="release/*" \
  -f push_access_level=40 \
  -f merge_access_level=40

ワークフロー 2：現在の保護設定を監査

# List all protections with details
glab api projects/123/protected_branches --paginate | \
  jq -r '.[] | "Branch: \(.name)\n  Push: \(.push_access_levels[0].access_level_description // "none")\n  Merge: \(.merge_access_levels[0].access_level_description // "none")\n  Force Push: \(.allow_force_push)\n"'

ワークフロー 3：本番ブランチをロックダウン

# Strict protection: only maintainers, no force push, require code owners
glab api projects/123/protected_branches --method POST \
  -f name="production" \
  -f push_access_level=40 \
  -f merge_access_level=40 \
  -f allow_force_push=false \
  -f code_owner_approval_required=true

ワークフロー 4：保護ブランチへのプッシュを一時的に許可

# 1. Check current protection
glab api projects/123/protected_branches/main

# 2. Update to allow developer push
glab api projects/123/protected_branches/main --method PATCH \
  -f push_access_level=30

# 3. Do the work...

# 4. Restore protection
glab api projects/123/protected_branches/main --method PATCH \
  -f push_access_level=40

ワークフロー 5：GitFlow の保護を設定

project_id=123

# Main - production (strict)
glab api projects/$project_id/protected_branches --method POST \
  -f name="main" \
  -f push_access_level=0 \
  -f merge_access_level=40 \
  -f allow_force_push=false

# Develop - integration
glab api projects/$project_id/protected_branches --method POST \
  -f name="develop" \
  -f push_access_level=30 \
  -f merge_access_level=30

# Feature branches - allow developers
glab api projects/$project_id/protected_branches --method POST \
  -f name="feature/*" \
  -f push_access_level=30 \
  -f merge_access_level=30

# Release branches - maintainers only
glab api projects/$project_id/protected_branches --method POST \
  -f name="release/*" \
  -f push_access_level=40 \
  -f merge_access_level=40

# Hotfix branches - maintainers only
glab api projects/$project_id/protected_branches --method POST \
  -f name="hotfix/*" \
  -f push_access_level=40 \
  -f merge_access_level=40

トラブルシューティング

問題	原因	解決策
403 Forbidden	Maintainer ではない	Maintainer 以上のロールが必要です
404 Not Found	ブランチが存在しない、または保護されていない	ブランチ名を確認してください
400 Bad Request	無効なアクセスレベル	0、30、40、60 のいずれかを使用してください
ブランチがまだ保護されている	パターンに一致している	ワイルドカードパターンを確認してください
保護ブランチにプッシュできない	アクセスレベルが低すぎる	保護設定を更新するか、より高いロールを取得してください

ベストプラクティス

1. 必ず main を保護する：少なくともデフォルトブランチを保護してください
2. ワイルドカードを適切に使う：個々のリリースではなく release/* を保護してください
3. main へのフォースプッシュを避ける：allow_force_push=false を設定してください
4. 保護設定を文書化する：ブランチ保護戦略を記録しておいてください
5. 定期的に見直す：保護設定を定期的に監査してください

関連ドキュメント

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