---

name: gitlab-api description: GitLab API integration for repository operations. Use when working with GitLab repositories for reading, writing, creating, or deleting files, listing projects, managing branches, or any other GitLab repository operations.

GitLab API

Interact with GitLab repositories via the REST API. Supports both GitLab.com and self-hosted instances.

Setup

Store your GitLab personal access token:

mkdir -p ~/.config/gitlab
echo "glpat-YOUR_TOKEN_HERE" > ~/.config/gitlab/api_token

Token scopes needed: api or read_api + write_repository

Get a token:

• GitLab.com: https://gitlab.com/-/user_settings/personal_access_tokens
• Self-hosted: https://YOUR_GITLAB/~/-/user_settings/personal_access_tokens

Configuration

Default instance: https://gitlab.com

For self-hosted GitLab, create a config file:

echo "https://gitlab.example.com" > ~/.config/gitlab/instance_url

Common Operations

List Projects

GITLAB_TOKEN=$(cat ~/.config/gitlab/api_token)
GITLAB_URL=$(cat ~/.config/gitlab/instance_url 2>/dev/null || echo "https://gitlab.com")

curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects?owned=true&per_page=20"

Get Project ID

Projects are identified by ID or URL-encoded path (namespace%2Fproject).

# By path
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/username%2Frepo"

# Extract ID from response: jq '.id'

Read File

PROJECT_ID="12345"
FILE_PATH="src/main.py"
BRANCH="main"

curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/repository/files/${FILE_PATH}?ref=$BRANCH" \
  | jq -r '.content' | base64 -d

Create/Update File

PROJECT_ID="12345"
FILE_PATH="src/new_file.py"
BRANCH="main"
CONTENT=$(echo "print('hello')" | base64)

curl -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/repository/files/${FILE_PATH}" \
  -d @- <<EOF
{
  "branch": "$BRANCH",
  "content": "$CONTENT",
  "commit_message": "Add new file",
  "encoding": "base64"
}
EOF

For updates, use -X PUT instead of -X POST.

Delete File

curl -X DELETE -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/repository/files/${FILE_PATH}" \
  -d '{"branch": "main", "commit_message": "Delete file"}'

List Files in Directory

curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/repository/tree?path=src&ref=main"

Get Repository Content (Archive)

curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/repository/archive.tar.gz" \
  -o repo.tar.gz

List Branches

curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/repository/branches"

Create Branch

curl -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  -H "Content-Type: application/json" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/repository/branches" \
  -d '{"branch": "feature-xyz", "ref": "main"}'

Helper Script

Use scripts/gitlab_api.sh for common operations:

# List projects
./scripts/gitlab_api.sh list-projects

# Read file
./scripts/gitlab_api.sh read-file <project-id> <file-path> [branch]

# Write file
./scripts/gitlab_api.sh write-file <project-id> <file-path> <content> <commit-msg> [branch]

# Delete file
./scripts/gitlab_api.sh delete-file <project-id> <file-path> <commit-msg> [branch]

# List directory
./scripts/gitlab_api.sh list-dir <project-id> <dir-path> [branch]

Rate Limits

• GitLab.com: 300 requests/minute (authenticated)
• Self-hosted: Configurable by admin

API Reference

Full API docs: https://docs.gitlab.com/ee/api/api_resources.html

Key endpoints:

• Projects: /api/v4/projects
• Repository files: /api/v4/projects/:id/repository/files
• Repository tree: /api/v4/projects/:id/repository/tree
• Branches: /api/v4/projects/:id/repository/branches