grandcamel Protected Branch Skill
Branch protection management for GitLab using glab api raw endpoint calls.
Quick Reference
| Operation | Command Pattern | Risk |
|---|---|---|
| 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
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)
API Prerequisites
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
Access Levels
| Level | Value | Description |
|---|---|---|
| No access | 0 | Nobody can perform action |
| Developer | 30 | Developers and above |
| Maintainer | 40 | Maintainers and above |
| Admin | 60 | Instance admins only |
Available Commands
List Protected Branches
# 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 Details
# 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)"
Protect a Branch
# 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
Update Protection
# 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
Warning: This removes all protection from the branch!
# 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
Protection Options
| Option | Type | Description |
|---|---|---|
name |
string | Branch name or wildcard pattern |
push_access_level |
integer | Who can push (0, 30, 40, 60) |
merge_access_level |
integer | Who can merge MRs (0, 30, 40, 60) |
unprotect_access_level |
integer | Who can unprotect (40, 60) |
allow_force_push |
boolean | Allow force push to branch |
code_owner_approval_required |
boolean | Require code owner approval (Premium) |
Wildcard Patterns
| Pattern | Matches |
|---|---|
* |
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. |
Common Workflows
Workflow 1: Standard Branch Protection
# 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
Workflow 2: Audit Current Protections
# 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"'
Workflow 3: Lock Down Production Branch
# 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
Workflow 4: Temporarily Allow Push to Protected Branch
# 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
Workflow 5: Set Up GitFlow Protection
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
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| 403 Forbidden | Not maintainer | Need Maintainer+ role |
| 404 Not Found | Branch doesn't exist or not protected | Check branch name |
| 400 Bad Request | Invalid access level | Use 0, 30, 40, or 60 |
| Branch still protected | Pattern match | Check for wildcard patterns |
| Cannot push to protected | Access level too low | Update protection or get higher role |
Best Practices
- Always protect main: At minimum, protect your default branch
- Use wildcards wisely: Protect
release/*instead of individual releases - Avoid force push on main: Set
allow_force_push=false - Document protections: Keep track of your branch protection strategy
- Review regularly: Audit protections periodically