GitLab API

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:

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

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   [branch]
Write file
./scripts/gitlab_api.sh write-file     [branch]
Delete file
./scripts/gitlab_api.sh delete-file    [branch]
List directory
./scripts/gitlab_api.sh list-dir   [branch]

Rate Limits

Default instance: https://gitlab.com

For self-hosted GitLab, create a config file:

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