mcpField
G
gitlab-protected-branch

gitlab-protected-branch

github.com/grandcamel安全488 次安装40 周前更新
代码仓库

关于 gitlab-protected-branch

通过 `glab api` 原始接口调用管理 GitLab 受保护分支的技能，供维护者查看并配置推送、合并、强制推送和代码所有者审批规则，并标示变更操作风险。

主要功能

  1. 01列出受保护分支
  2. 02查看分支保护规则
  3. 03设置和更新访问级别
  4. 04配置强制推送与代码所有者规则
  5. 05移除分支保护

适用场景

  1. 01审计项目分支保护设置
  2. 02限制 main 分支的推送或合并
  3. 03为发布分支应用通配规则
  4. 04临时调整受保护分支的访问权限

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/grandcamel/gitlab-assistant-skills --skill gitlab-protected-branch

安装后在 Claude Code 中输入/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 及以上

高级功能：

  • 代码所有者审批：GitLab Premium
  • 多种访问级别：GitLab Premium

访问级别

级别值说明
无访问权限0任何人都无法执行操作
Developer30Developer 及以上
Maintainer40Maintainer 及以上
Admin60仅限实例管理员

可用命令

列出受保护分支
# 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

保护选项

选项类型说明
namestring分支名称或通配符模式
push_access_levelinteger允许推送的人员（0、30、40、60）
merge_access_levelinteger允许合并 MR 的人员（0、30、40、60）
unprotect_access_levelinteger允许取消保护的人员（40、60）
allow_force_pushboolean是否允许强制推送到分支
code_owner_approval_requiredboolean是否需要代码所有者审批（Premium）

通配符模式

模式匹配项
*所有分支
feature/*feature/login、feature/signup 等
release/*release/1.0、release/2.0 等
hotfix/*hotfix/bug-123 等
*-stable1.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. 定期检查：定期审计保护设置

相关文档

评论

支持 Markdown