glab repo

Work with GitLab repositories and projects.

Repository URLs returned by the API are validated before glab passes them to Git. Supported URL schemes and scp-like SSH syntax are accepted; option-like strings, remote-helper transports, whitespace, and control characters are rejected. If a clone, fork, or remote operation fails with an invalid remote URL, inspect the exact trusted project/host metadata rather than bypassing validation or handing that string directly to Git.

Full clone URLs and host routing

A plain repo clone <full-URL> passes the URL to Git without requiring a GitLab API client or current-user lookup. Git still handles transport authentication; this does not make a private clone anonymous. Namespace/project shorthand and group cloning still use the selected GitLab host/API context.

A full-URL --wiki clone does use the API on the URL's own host, including a port, rather than the configured default host. It strips that host's configured subfolder before the project lookup and obtains the wiki URL from the project. Review the exact URL host before cloning: stored or environment credentials can be sent to it. A trusted authenticated host:port/group/project repository selector is recognized by --repo; use a full URL to make a nonstandard endpoint unambiguous.

repo view reads the README even when the default branch contains a slash. Fork creation waits between import-status polls; allow it to finish and inspect the existing fork before retrying. Clone writes locally and fork creation writes remotely, so approve the intended destinations and side effects first.

Quick start

# Clone a repository
glab repo clone group/project

# Clone the project's wiki repository
glab repo clone --wiki group/project

# Create new repository
glab repo create my-new-project --public

# Fork a repository
glab repo fork upstream/project

# View repository details
glab repo view

# Add a Git remote from a GitLab project reference
glab repo remote add group/project --name upstream

# Prune local branches whose MRs have been merged
glab repo prune --dry-run
glab repo prune --yes

# Search for repositories
glab repo search "keyword"

Common workflows

Starting new project

When --private, --internal, and --public are all omitted, GitLab uses the instance's default project visibility. Specify the intended visibility explicitly when creating a project.

1. Create repository:

   glab repo create my-project \
     --public \
     --description "My awesome project"
   
   # Create with README
   glab repo create my-project \
     --public \
     --readme

   Note: glab repo create --readme clones the newly created repository instead of using git init, ensuring a clean local copy with the initial README.

   glab repo create --skipGitInit creates the remote project without prompting to initialize a local directory. If the current directory is not already a Git repository, glab also skips adding a remote instead of emitting a misleading fatal: not a git repository warning after successful remote creation.

   A path containing nested groups preserves the complete namespace. For example, glab repo create group/subgroup/my-project creates my-project under group/subgroup, not only the final subgroup.

2. Clone locally (if not using --readme):

   glab repo clone my-username/my-project
   cd my-project

   To clone only the GitLab wiki, pass --wiki with one project reference. It cannot be combined with group-wide --group cloning, and it fails clearly when the project's wiki is disabled.

   glab repo clone --wiki group/project

   SSH configurations that map gitlab.com to the official altssh.gitlab.com endpoint are recognized as GitLab.com rather than as a separate self-managed host.

   For self-managed hosts that include a port, glab keys subfolder config lookup on the full host with port. If a repository resolves to the wrong API host or misses a configured subfolder, verify the exact host key in the config file at glab config path includes the port.

3. Initialize with content:

   echo "# My Project" > README.md
   git add README.md
   git commit -m "Initial commit"
   git push -u origin main

Forking workflow

1. Fork upstream repository:

   glab repo fork upstream-group/project

2. Clone your fork:

   glab repo clone my-username/project
   cd project

3. Add upstream remote:

   glab repo remote add upstream-group/project --name upstream

   glab repo remote add <namespace/project> resolves a GitLab project reference and adds the appropriate Git remote URL. The default remote name is the first path component (upstream-group in the example); override it with --name / -n. Use --protocol ssh|https / -p to override the git_protocol config.

   glab repo remote add alice/my-project
   glab repo remote add alice/my-project --name upstream
   glab repo remote add group/subgroup/my-project --protocol ssh

4. Keep fork in sync:

   git fetch upstream
   git merge upstream/main

Automated sync:

Use the sync script bundled with this skill under scripts/ for one-command fork updates (paths below are relative to the skill's own directory):

scripts/sync-fork.sh main
scripts/sync-fork.sh develop upstream

This automatically: fetches → merges → pushes to origin.

Repository management

View repository info:

glab repo view
glab repo view group/project  # Specific repo
glab repo view --web          # Open in browser

Update repository settings:

glab repo update \
  --description "Updated description" \
  --default-branch develop

Archive repository:

glab repo archive download main  # Downloads .tar.gz
glab repo archive download main --format zip

Transfer to new namespace:

glab repo transfer my-project --target-namespace new-group

Delete repository:

glab repo delete group/project

Local branch pruning

glab repo prune deletes local Git branches whose GitLab merge requests have been merged. It never deletes remote branches on GitLab, and it skips protected branches, the default branch, and the branch currently checked out.

# Preview branches that would be deleted
glab repo prune --dry-run

# Delete branches after confirmation
glab repo prune

# Delete without confirmation after reviewing the dry run
glab repo prune --yes

# Exclude additional branches by exact name or glob; comma-separate or repeat
glab repo prune --exclude wip-*,demo-branch

# Faster local-Git detection; misses squash/rebase merges that are not fast-forward ancestry
glab repo prune --merged

Prefer the default GitLab-backed mode for correctness: it queries merge requests for each local branch and handles squash/rebase merge cases better than plain git branch --merged. Use --merged only when the faster fast-forward-only check is acceptable.

Member management

List collaborators:

glab repo members list

Add member:

glab repo members add @username --access-level maintainer

Remove member:

glab repo members remove @username

Update member access:

glab repo members update @username --access-level developer

Bulk operations

Clone all repos in a group:

glab repo clone -g my-group

# Skip selected subgroups and their descendants across every page
glab repo clone -g my-group --exclude-subgroup domain/backend,archived --paginate

--exclude-subgroup accepts subgroup paths relative to --group, not numeric subgroup IDs. Repeat the flag or comma-separate paths. Matching is case-insensitive, trims leading/trailing slashes, accepts paths prefixed with the full group path, and respects path boundaries (team does not exclude team-other). A numeric --group ID is resolved to its full path before filtering. Projects shared from other namespaces are unaffected. Subgroups are included by default; exclusions filter the fetched projects before cloning. If every fetched project is excluded, the command fails with a “No projects left to clone” message.

Search and clone:

glab repo search "api" --per-page 10
# Then clone specific result
glab repo clone group/api-project

List your repositories:

glab repo list
glab repo list --member          # Only where you're a member
glab repo list --mine            # Only repos you own

Troubleshooting

Clone fails with permission error:

• Verify you have access: glab repo view group/project
• Check authentication: glab auth status
• For private repos, ensure you're logged in with correct account

Fork operation fails:

• Check if fork already exists in your namespace
• Verify you have permission to fork (some repos disable forking)
• Try with explicit namespace: glab repo fork --fork-path username/new-name

Transfer fails:

• Verify you have owner/maintainer access
• Check target namespace exists and you have create permissions
• Some projects may have transfer protections enabled

Group clone fails:

• Verify group exists and you have access
• Check you have enough disk space
• Large groups may time out - clone specific repos instead

Related Skills

Authentication and access:

• See glab-auth for login and authentication setup
• See glab-ssh-key for SSH key management
• See glab-deploy-key for deployment authentication

Project configuration:

• See glab-config for CLI defaults and settings
• See glab-variable for CI/CD variables

Fork synchronization:

• Script: scripts/sync-fork.sh automates upstream sync

Structured output

glab repo contributors supports --output json / -F json for structured output, which is useful for agent automation.

# List contributors with JSON output
glab repo contributors --output json
glab repo contributors -F json

Command reference

For complete command documentation and all flags, see references/commands.md.

Available commands:

• clone - Clone repository or group
• create - Create new project
• fork - Fork repository
• view - View project details
• update - Update project settings
• delete - Delete project
• search - Search for projects
• list - List repositories
• transfer - Transfer to new namespace
• archive - Download repository archive
• contributors - List contributors
• members - Manage project members
• mirror - Configure repository mirroring
• remote - Manage Git remotes using GitLab project references
• prune - Delete local branches whose GitLab merge requests are merged
• publish - Publish project resources