Gitlab Branch Manager

GitLab Branch Manager

Overview

Create GitLab branches and apply protection rules. Designed for release workflows but usable for any branch management scenario.

Prerequisites:

• glab command is available and authenticated
• Works with gitlab.com, GitLab Self-Managed, and GitLab Dedicated
• jq for JSON parsing

Dependency Installation: Before running any script, install required tools using the centralized installers:

../../../tools/glab/install.sh    # Install glab if not present
../../../tools/jq/install.sh      # Install jq if not present

The installers are idempotent and included in allowed-tools. Scripts assume CLIs are available after installation.

Core Concepts

• Protected Branch: A branch with restrictions on who can push, merge, force-push, and unprotect
• Access Levels: 0 = No access, 30 = Developer, 40 = Maintainer, 60 = Admin (self-managed only)

Default Protection Rules

| Rule | Default | Effect | |------|---------|--------| | push_access_level | 0 (No access) | Direct push blocked for everyone | | merge_access_level | 40 (Maintainer) | Only maintainers can merge MRs | | allow_force_push | false | Force push blocked | | code_owner_approval_required | false | No code owner approval required |

All rules are configurable via flags. Defaults enforce a strict protection posture suitable for release branches, matching the pattern used in production repositories.

Note: unprotect_access_level is not set by default (uses GitLab server default). Use --unprotect-level or --rule unprotect_access_level=40 to set it explicitly.

Note: push_access_level=0 already blocks direct push and deletion for everyone.

Repo Input Format

The script accepts three input formats:

| Format | Example | Resolution | |--------|---------|------------| | Short name | my-project | Resolved via GitLab API search | | Full path | my-org/my-group/my-project | Used as-is | | URL | https://gitlab.com/my-org/my-group/my-project.git | Parsed to extract project path |

Script Reference

create_and_protect_branch.sh

Creates a branch and applies protection rules in a single operation.

Usage:

./scripts/create_and_protect_branch.sh    [OPTIONS]

IMPORTANT: All three positional arguments are required and must appear in this exact order. There is no --ref flag — the ref is always the third positional argument.

Positional arguments (required, in order):

| Position | Argument | Description | |----------|----------|-------------| | 1 | ` | Repo name, full path, or URL | | 2 | | Name for the new branch | | 3 | ` | Source ref to branch from (tag, commit SHA, or branch name) |

Options (all optional):

| Option | Default | Description | |--------|---------|-------------| | --push-level N | 0 | Push access level | | --merge-level N | 40 | Merge access level | | --unprotect-level N | not set | Unprotect access level | | --allow-force-push | false | Allow force push | | --code-owner-approval | false | Require code owner approval | | --gitlab-host HOST | gitlab.com | GitLab hostname | | --rule KEY=VALUE | -- | Override any protection rule by key | | --dry-run | -- | Show planned actions, no API calls | | --human-readable | -- | Human-readable output |

Examples:

# Create and protect a release branch from a tag
./scripts/create_and_protect_branch.sh my-project release-1.5 v1.4.0

# Branch from main
./scripts/create_and_protect_branch.sh my-org/my-group/my-project release-1.5 main

# Custom protection levels
./scripts/create_and_protect_branch.sh my-project release-1.5 v1.4.0 --push-level 40 --merge-level 40

# Override any rule with --rule
./scripts/create_and_protect_branch.sh my-project release-1.5 v1.4.0 --rule merge_access_level=30

# Dry run - see what would happen
./scripts/create_and_protect_branch.sh my-project release-1.5 v1.4.0 --dry-run

# From a URL
./scripts/create_and_protect_branch.sh https://gitlab.com/my-org/my-group/my-project.git release-1.5 v1.4.0

Output (JSON, default):

{
  "repository": "my-org/my-group/my-project",
  "branch": "release-1.5",
  "ref": "main",
  "branch_created": true,
  "protection_applied": true,
  "protection_rules": {
    "push_access_level": 0,
    "merge_access_level": 40,
    "allow_force_push": false,
    "code_owner_approval_required": false
  }
}

Error Handling

| Scenario | Behavior | |----------|----------| | Branch already exists | Exit 1 with error JSON | | Protection matches requested rules | Exit 0, info logged to stderr | | Protection differs from requested | Exit 1 with error JSON showing current vs requested rules | | Source ref not found | Exit 1 with error JSON | | Insufficient permissions | Exit 1 with error JSON | | Short name matches multiple projects | Exit 1 with error JSON listing candidates |

Dependencies

Required: glab, jq — installed automatically via tools/*/install.sh (see Dependency Installation above)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aipcc-cicd
• Source: aipcc-cicd/claudio-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.