Back to Details

gitlab-protected-branch

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Protected Branch Skill

受保护分支技能

Branch protection management for GitLab using 
glab api
raw endpoint calls.
使用
glab api
原始端点调用管理GitLab的分支保护。

Quick Reference

快速参考

OperationCommand PatternRisk
List protected
glab api projects/:id/protected_branches
-
Get protection
glab api projects/:id/protected_branches/:name
-
Protect branch
glab api projects/:id/protected_branches -X POST -f ...
⚠️
Update protection
glab api projects/:id/protected_branches/:name -X PATCH -f ...
⚠️
Unprotect branch
glab api projects/:id/protected_branches/:name -X DELETE
⚠️⚠️
Risk Legend: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger
操作命令模板风险
列出受保护分支
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
⚠️⚠️
风险图例: - 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

When to Use This Skill

何时使用该技能

ALWAYS use when:
  • User mentions "protect branch", "branch protection", "protected branches"
  • User wants to restrict who can push/merge to a branch
  • User mentions "force push", "code owners", "merge access"
  • User wants to configure main/release branch security
NEVER use when:
  • User wants to create/delete branches (use git or gitlab-repo)
  • User wants to manage merge request approvals (different API)
  • User wants to configure CI/CD for branches (use gitlab-ci)
请务必在以下场景使用:
  • 用户提及"protect branch"、"branch protection"、"protected branches"
  • 用户希望限制谁可以向分支推送/合并代码
  • 用户提及"force push"、"code owners"、"merge access"
  • 用户希望配置主分支/发布分支的安全性
请勿在以下场景使用:
  • 用户想要创建/删除分支（使用git或gitlab-repo）
  • 用户想要管理合并请求审批（使用不同的API）
  • 用户想要为分支配置CI/CD（使用gitlab-ci）

API Prerequisites

API前置要求

Required Token Scopes: 
api
Permissions:
  • View protected branches: Developer+
  • Manage protected branches: Maintainer+
Premium Features:
  • Code owner approval: GitLab Premium
  • Multiple access levels: GitLab Premium
所需令牌权限范围: 
api
权限:
  • 查看受保护分支：开发者及以上角色
  • 管理受保护分支：维护者及以上角色
高级功能:
  • 代码所有者审批：GitLab Premium
  • 多权限等级：GitLab Premium

Access Levels

权限等级

LevelValueDescription
No access0Nobody can perform action
Developer30Developers and above
Maintainer40Maintainers and above
Admin60Instance admins only
等级数值描述
无权限0无人可执行操作
开发者30开发者及以上角色
维护者40维护者及以上角色
管理员60仅实例管理员

Available Commands

可用命令

List Protected Branches

列出受保护分支

bash
undefined
bash
undefined

List all protected branches

List all protected branches

glab api projects/123/protected_branches --method GET
glab api projects/123/protected_branches --method GET

With pagination

With pagination

glab api projects/123/protected_branches --paginate
glab api projects/123/protected_branches --paginate

Using project path

Using project path

glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/protected_branches"
undefined
glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/protected_branches"
undefined

Get Protection Details

获取保护规则详情

bash
undefined
bash
undefined

Get protection for specific branch

Get protection for specific branch

glab api projects/123/protected_branches/main --method GET
glab api projects/123/protected_branches/main --method GET

Branch with special characters (URL-encode)

Branch with special characters (URL-encode)

glab api "projects/123/protected_branches/$(echo 'release/1.0' | jq -Rr @uri)"
glab api "projects/123/protected_branches/$(echo 'release/1.0' | jq -Rr @uri)"

Branch with wildcard pattern

Branch with wildcard pattern

glab api "projects/123/protected_branches/$(echo 'feature/*' | jq -Rr @uri)"
undefined
glab api "projects/123/protected_branches/$(echo 'feature/*' | jq -Rr @uri)"
undefined

Protect a Branch

保护分支

bash
undefined
bash
undefined

Basic protection (maintainers push, developers merge)

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
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)

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
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)

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
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

Protect wildcard pattern

glab api projects/123/protected_branches --method POST
-f name="release/*"
-f push_access_level=40
-f merge_access_level=40
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

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
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)

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
undefined
glab api projects/123/protected_branches --method POST
-f name="main"
-f push_access_level=0
-f merge_access_level=30
undefined

Update Protection

更新保护规则

bash
undefined
bash
undefined

Change merge access level

Change merge access level

glab api projects/123/protected_branches/main --method PATCH
-f merge_access_level=40
glab api projects/123/protected_branches/main --method PATCH
-f merge_access_level=40

Enable code owner approval (Premium)

Enable code owner approval (Premium)

glab api projects/123/protected_branches/main --method PATCH
-f code_owner_approval_required=true
glab api projects/123/protected_branches/main --method PATCH
-f code_owner_approval_required=true

Allow force push (not recommended for main)

Allow force push (not recommended for main)

glab api projects/123/protected_branches/feature%2F* --method PATCH
-f allow_force_push=true
undefined
glab api projects/123/protected_branches/feature%2F* --method PATCH
-f allow_force_push=true
undefined

Unprotect Branch

取消分支保护

Warning: This removes all protection from the branch!
bash
undefined
警告: 此操作会移除该分支的所有保护规则！
bash
undefined

Unprotect branch

Unprotect branch

glab api projects/123/protected_branches/main --method DELETE
glab api projects/123/protected_branches/main --method DELETE

Unprotect wildcard pattern (URL-encode)

Unprotect wildcard pattern (URL-encode)

glab api "projects/123/protected_branches/$(echo 'feature/*' | jq -Rr @uri)" --method DELETE
undefined
glab api "projects/123/protected_branches/$(echo 'feature/*' | jq -Rr @uri)" --method DELETE
undefined

Protection Options

保护选项

OptionTypeDescription
name
stringBranch name or wildcard pattern
push_access_level
integerWho can push (0, 30, 40, 60)
merge_access_level
integerWho can merge MRs (0, 30, 40, 60)
unprotect_access_level
integerWho can unprotect (40, 60)
allow_force_push
booleanAllow force push to branch
code_owner_approval_required
booleanRequire code owner approval (Premium)
选项类型描述
name
字符串分支名称或通配符模式
push_access_level
整数允许推送的角色（0, 30, 40, 60）
merge_access_level
整数允许合并MR的角色（0, 30, 40, 60）
unprotect_access_level
整数允许取消保护的角色（40, 60）
allow_force_push
布尔值是否允许强制推送至该分支
code_owner_approval_required
布尔值是否要求代码所有者审批（高级版）

Wildcard Patterns

通配符模式

PatternMatches
*
All branches
feature/*
feature/login
, 
feature/signup
, etc.
release/*
release/1.0
, 
release/2.0
, etc.
hotfix/*
hotfix/bug-123
, etc.
*-stable
1.0-stable
, 
2.0-stable
, etc.
模式匹配对象
*
所有分支
feature/*
feature/login
、
feature/signup
等
release/*
release/1.0
、
release/2.0
等
hotfix/*
hotfix/bug-123
等
*-stable
1.0-stable
、
2.0-stable
等

Common Workflows

常见工作流

Workflow 1: Standard Branch Protection

工作流1: 标准分支保护

bash
undefined
bash
undefined

Protect main branch

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
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

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
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

Protect release branches

glab api projects/123/protected_branches --method POST
-f name="release/*"
-f push_access_level=40
-f merge_access_level=40
undefined
glab api projects/123/protected_branches --method POST
-f name="release/*"
-f push_access_level=40
-f merge_access_level=40
undefined

Workflow 2: Audit Current Protections

工作流2: 审计当前保护规则

bash
undefined
bash
undefined

List all protections with details

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"'
undefined
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"'
undefined

Workflow 3: Lock Down Production Branch

工作流3: 锁定生产分支

bash
undefined
bash
undefined

Strict protection: only maintainers, no force push, require code owners

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
undefined
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
undefined

Workflow 4: Temporarily Allow Push to Protected Branch

工作流4: 临时允许向受保护分支推送

bash
undefined
bash
undefined

1. Check current protection

1. Check current protection

glab api projects/123/protected_branches/main
glab api projects/123/protected_branches/main

2. Update to allow developer push

2. Update to allow developer push

glab api projects/123/protected_branches/main --method PATCH
-f push_access_level=30
glab api projects/123/protected_branches/main --method PATCH
-f push_access_level=30

3. Do the work...

3. Do the work...

4. Restore protection

4. Restore protection

glab api projects/123/protected_branches/main --method PATCH
-f push_access_level=40
undefined
glab api projects/123/protected_branches/main --method PATCH
-f push_access_level=40
undefined

Workflow 5: Set Up GitFlow Protection

工作流5: 配置GitFlow分支保护

bash
project_id=123
bash
project_id=123

Main - production (strict)

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
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

Develop - integration

glab api projects/$project_id/protected_branches --method POST
-f name="develop"
-f push_access_level=30
-f merge_access_level=30
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

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
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

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
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

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
undefined
glab api projects/$project_id/protected_branches --method POST
-f name="hotfix/*"
-f push_access_level=40
-f merge_access_level=40
undefined

Troubleshooting

故障排查

IssueCauseSolution
403 ForbiddenNot maintainerNeed Maintainer+ role
404 Not FoundBranch doesn't exist or not protectedCheck branch name
400 Bad RequestInvalid access levelUse 0, 30, 40, or 60
Branch still protectedPattern matchCheck for wildcard patterns
Cannot push to protectedAccess level too lowUpdate protection or get higher role
问题原因解决方案
403 Forbidden非维护者角色需要维护者及以上角色
404 Not Found分支不存在或未被保护检查分支名称
400 Bad Request无效的权限等级使用0、30、40或60
分支仍处于保护状态通配符模式匹配检查是否存在通配符保护规则
无法向受保护分支推送权限等级过低更新保护规则或获取更高角色权限

Best Practices

最佳实践

  1. Always protect main: At minimum, protect your default branch
  2. Use wildcards wisely: Protect 
    release/*
    instead of individual releases
  3. Avoid force push on main: Set 
    allow_force_push=false
  4. Document protections: Keep track of your branch protection strategy
  5. Review regularly: Audit protections periodically
  1. 始终保护主分支: 至少保护你的默认分支
  2. 合理使用通配符: 保护
    release/*
    而非单个发布分支
  3. 主分支禁止强制推送: 设置
    allow_force_push=false
  4. 记录保护规则: 记录你的分支保护策略
  5. 定期审核: 定期审计保护规则

Related Documentation

相关文档