GitLab Operations

This skill enables comprehensive GitLab operations including creating and cloning repositories, listing projects, managing issues, merge requests, branches, commits, pipelines, and more.

Configuration

The GitLab skill uses a secure, layered credential management system. Credentials are loaded in the following priority order:

1. Environment Variables (Recommended - Most Secure) ⭐

Set GitLab credentials as environment variables:

export GITLAB_HOST="https://gitlab.example.com"
export GITLAB_TOKEN="glpat-your-token-here"

Benefits:
- Most secure approach
- Never committed to version control
- Standard practice for production systems
- Works seamlessly with CI/CD pipelines

Generating a GitLab Access Token:
1. Go to GitLab → User Settings → Access Tokens
2. Create a personal access token with appropriate scopes:
- api - Full API access
- read_repository - For repository operations
- write_repository - For creating branches, commits, etc.
3. Copy the token immediately (you won't see it again)

Persistent Configuration:
Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export GITLAB_HOST="https://gitlab.example.com"
export GITLAB_TOKEN="glpat-your-token-here"

2. User Configuration File

Create a configuration file in your home directory:

mkdir -p ~/.claude
cat > ~/.claude/gitlab_config.json << 'EOF'
{
  "host": "https://gitlab.example.com",
  "access_token": "glpat-your-token-here"
}
EOF

chmod 600 ~/.claude/gitlab_config.json  # Restrict file permissions

Location: ~/.claude/gitlab_config.json

Benefits:
- Secure location outside skill directory
- Won't be accidentally committed
- Easy to manage multiple GitLab instances
- Supports file-based automation

3. Runtime Prompt (Fallback)

If credentials are not found in environment variables or config files, the skill can prompt for credentials interactively (when the --allow-prompt flag is used):

python3 scripts/gitlab_api.py projects --allow-prompt

Note: This is not recommended for automation or CI/CD pipelines.

Configuration Priority

The skill loads credentials in this order (first match wins):

1. Environment Variables (GITLAB_HOST, GITLAB_TOKEN) - Highest Priority
2. User Config File (~/.claude/gitlab_config.json)
3. Legacy Config (scripts/config.json - deprecated, shows warning)
4. Runtime Prompt (only if --allow-prompt flag is used)

Example Config File Template

An example configuration template is available at scripts/config.example.json:

{
  "host": "https://gitlab.example.com",
  "access_token": "glpat-your-token-here"
}

Important Security Notes

DO:
✅ Use environment variables for production systems
✅ Store user config in ~/.claude/gitlab_config.json
✅ Restrict file permissions: chmod 600 ~/.claude/gitlab_config.json
✅ Use different tokens for different environments
✅ Rotate tokens regularly

DON'T:
❌ Commit credentials to version control
❌ Store real tokens in scripts/config.json
❌ Share access tokens in chat logs or output
❌ Use the same token across multiple environments
❌ Print or log access tokens

SSL Certificate Issues

For internal GitLab instances with self-signed certificates, use the --insecure flag:

python3 scripts/gitlab_api.py projects --insecure

This bypasses SSL certificate verification (useful for development/testing but not recommended for production).

Testing Credential Loading

Test that credentials are configured correctly:

# Test using credential loader directly
python3 scripts/credential_loader.py --show-source

# List projects to verify API access
python3 scripts/gitlab_api.py projects

# Check which credential source is being used
python3 scripts/gitlab_api.py projects --allow-prompt

Troubleshooting

Problem: "GitLab credentials not configured"

Solutions:
1. Check environment variables: echo $GITLAB_HOST $GITLAB_TOKEN
2. Check user config: cat ~/.claude/gitlab_config.json
3. Verify token is valid and not expired
4. Ensure token has required API scopes

Problem: "Authentication failed (401)"

Solutions:
1. Verify token hasn't expired or been revoked
2. Check token has required scopes (api, read_repository, etc.)
3. Ensure token format is correct (starts with glpat-)
4. Test token manually:
bash curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "$GITLAB_HOST/api/v4/user"

Problem: "Resource not found (404)"

Solutions:
1. Verify GitLab host URL is correct
2. Check project ID or path
3. Ensure user has access to the project
4. Test with python3 scripts/gitlab_api.py projects to list accessible projects

Migration from Old Configuration

If you have an existing scripts/config.json file:

1. Immediate Action: Move credentials to secure location
   ```bash
   # Export to environment variables
   export GITLAB_HOST=$(jq -r '.host' scripts/config.json)
   export GITLAB_TOKEN=$(jq -r '.access_token' scripts/config.json)

# Or move to user config
mkdir -p ~/.claude
cp scripts/config.json ~/.claude/gitlab_config.json
chmod 600 ~/.claude/gitlab_config.json
```

2. Replace config.json with placeholder:
   bash cat > scripts/config.json << 'EOF' { "_comment": "This file is deprecated", "host": "https://gitlab.example.com", "access_token": "glpat-your-token-here" } EOF

3. Verify new configuration works:
   bash python3 scripts/credential_loader.py --show-source python3 scripts/gitlab_api.py projects

Common Operations

Create Repository

When the user wants to create a new GitLab repository:

1. Prompt for required information:
   - Project name (required)
   - Description (optional)
   - Visibility level: public, private, or internal (optional, defaults to private)
   - Namespace/group path (optional, defaults to user's personal namespace)
   - Initialize with README (optional, defaults to false)
2. Use POST /api/v4/projects endpoint with the provided parameters
3. Include additional options if specified:
   - initialize_with_readme: Create repository with initial README
   - default_branch: Set default branch name (defaults to "main")
   - wiki_enabled: Enable wiki (defaults to true)
   - issues_enabled: Enable issues (defaults to true)
   - merge_requests_enabled: Enable merge requests (defaults to true)
   - jobs_enabled: Enable CI/CD pipelines (defaults to true)
4. Handle response and provide:
   - Project URL
   - Git clone URL
   - Web URL
   - Project ID
   - Confirmation with formatted Markdown output

Example output format:

## ✅ Repository Created Successfully

**Project**: my-project
**Project ID**: 123
**Visibility**: Private
**URL**: [View Project](https://gitlab.example.com/username/my-project)
**Clone**: `git clone https://gitlab.example.com/username/my-project.git`

Error handling:
- Name already exists: Suggest alternative names
- Invalid namespace: List available namespaces
- Permission denied: Check user permissions and token scopes

Clone Repository

When the user wants to clone a GitLab repository:

1. Parse the repository URL to extract the project path and host
2. Verify the host matches the configured GitLab instance in config.json
3. If authentication is required for private repositories, use the access token from config
4. Clone to the specified directory or current directory if not specified
5. Use git clone with appropriate authentication:
   - For HTTPS: use token as password
   - For SSH: use git@host:project-path.git format
6. Confirm successful clone with repository path and brief info

Example workflow:

User: "clone https://gitlab.example.com/group/project to ./myproject"
Action:
1. Extract host (gitlab.example.com) and project path (group/project)
2. Run git clone with authentication
3. Confirm: "✅ Cloned to ./myproject"

Authentication note: For private repos requiring HTTPS auth, embed token in URL: https://oauth2:TOKEN@host/project.git

List Repositories/Projects

When the user wants to see their GitLab repositories:

1. Load configuration from config.json
2. Fetch all projects using the GitLab API (/api/v4/projects)
3. Use membership=true to show only projects the user is a member of
4. Sort by updated_at descending to show recently updated projects first
5. Handle pagination automatically to fetch all projects
6. Output results in Markdown format with:
   - Project count summary
   - Formatted table with: Name, Visibility, Last Updated, URL
   - Group/namespace information if relevant
   - Links to each project

Example output format:

## Found 25 GitLab Projects

| Name | Visibility | Last Updated | URL |
|------|------------|--------------|-----|
| group/project-name | Public | 2025-04-02 | [View](https://gitlab.example.com/group/project-name) |
...

Search Projects

When the user wants to search for specific projects:

1. Use the /api/v4/projects endpoint with search=<query> parameter
2. Filter by visibility if requested (visibility=public|private|internal)
3. Limit results to top 20 matches unless more are requested
4. Output in Markdown table format

Project Details

When the user asks about a specific project:

1. Use /api/v4/projects/:id endpoint (project ID or path-encoded URL)
2. Fetch detailed information including:
   - Description, default branch, star count, forks count
   - Last activity date
   - Repository size
   - Permissions
3. Output in formatted Markdown with sections for each detail category

Issues

List issues:
- Use /api/v4/projects/:id/issues for project-specific issues
- Use /api/v4/issues for all issues across projects
- Support filtering: state (opened/closed), labels, milestone, assignee
- Output in Markdown table with: ID, Title, State, Author, Assignee, Updated, Link

Create issue:
- Use POST /api/v4/projects/:id/issues
- Required: title
- Optional: description, labels, assignee_id, milestone_id
- Ask user for missing required information
- Confirm creation and show the issue URL

Get issue details:
- Use GET /api/v4/projects/:id/issues/:issue_iid
- Fetch complete issue information including description, labels, assignees
- Output formatted Markdown with all issue details
- Show state icon (🟢 opened, 🔴 closed), author, assignees, labels, milestone
- Display full description and link to issue in GitLab
- Handle missing fields gracefully with "None" or "Unassigned" placeholders

Update issue:
- Use PUT /api/v4/projects/:id/issues/:issue_iid
- Allow updating title, description, state, labels, etc.
- Confirm changes and show updated issue link

Merge Requests

List merge requests:
- Use /api/v4/projects/:id/merge_requests for project-specific MRs
- Use /api/v4/merge_requests for all MRs across projects
- Support filtering: state (opened/closed/merged), author, assignee, labels
- Output in Markdown table with: IID, Title, State, Author, Target Branch, Source Branch, Link

Create merge request:
- Use POST /api/v4/projects/:id/merge_requests
- Required: source_branch, target_branch, title
- Optional: description, assignee_id, labels, remove_source_branch
- Ask user for missing required information
- Confirm creation and show MR URL

Show MR details:
- Fetch MR with discussions, changes, and pipeline status
- Output comprehensive Markdown with:
- Basic info (title, state, branches, author)
- Changes summary (files changed, additions, deletions)
- Pipeline status if available
- Recent discussions/comments

Branches

List branches:
- Use /api/v4/projects/:id/repository/branches
- Show name, protected status, commit info, last commit date
- Output in Markdown table

Create branch:
- Use POST /api/v4/projects/:id/repository/branches
- Required: branch_name, ref (starting branch or commit SHA)
- Confirm creation with branch details including:
- Branch name and protection status (🔒 protected icon)
- Latest commit SHA, message, author, and date
- Link to branch in GitLab
- Handle errors gracefully:
- Branch already exists (400 error)
- Invalid branch name or ref (400 error)
- Invalid project or insufficient permissions (403/404 errors)

Delete branch:
- Use DELETE /api/v4/projects/:id/repository/branches/:branch
- Warn before deletion
- Confirm deletion

Commits

List commits:
- Use /api/v4/projects/:id/repository/commits
- Support filtering: ref_name (branch), since, until, author
- Show short SHA, author, message, date
- Output in Markdown table with links to commit diffs

Show commit details:
- Use /api/v4/projects/:id/repository/commits/:sha
- Show full commit message, author, committer, file changes
- Display diff summary

Pipelines

List pipelines:
- Use /api/v4/projects/:id/pipelines
- Show ID, status, ref, user, created date, duration
- Output in Markdown table with status indicators (✅ ✗ ⏳)

Show pipeline details:
- Fetch pipeline jobs and stages
- Display job status, duration, and logs URLs
- Show overall pipeline status and timing

Error Handling

When encountering errors:

1. Authentication failed (401/403):
   - Inform user the access token may be invalid or lacks required permissions
   - Suggest checking config.json or generating a new token with appropriate scopes

2. Project not found (404):
   - Verify project ID or path
   - Check if user has access to the project
   - Suggest listing projects to find the correct ID

3. Rate limiting (429):
   - Inform user about rate limits
   - Suggest waiting before retrying

4. Network errors:
   - Check if GitLab host is reachable
   - Verify network connection
   - For internal GitLab instances with self-signed certificates, handle SSL verification appropriately

5. Invalid parameters:
   - Explain what parameter was invalid
   - Provide guidance on correct values
   - Show API documentation links if relevant

API Pagination

For endpoints that return paginated results:
1. Check x-total-pages header
2. Iterate through all pages to fetch complete results
3. For large result sets (>100 items), ask user if they want all results or just the first N
4. Show progress when fetching multiple pages

Output Formatting Principles

1. Use Markdown for all human-readable output - tables, lists, code blocks
2. Include links to relevant GitLab resources - project URLs, issue links, MR links
3. Show counts and summaries - total results, filtered counts
4. Use visual indicators for status - ✅ for success, ✗ for failure, ⏳ for pending
5. Format dates in readable format - YYYY-MM-DD or relative time (2 days ago)
6. Truncate long text - commit messages, descriptions, with option to show full text
7. Group related information - use headers and sections for complex outputs

Interactive Workflows

For complex operations requiring multiple steps:

1. Ask for confirmation before destructive operations (delete, close, etc.)
2. Offer choices when there are multiple valid approaches
3. Suggest next actions after completing an operation (e.g., after creating an issue, ask if they want to create another)
4. Handle ambiguous inputs - if a project name is ambiguous, show matching projects and ask user to select

Example Workflows

User asks: "Show me my open merge requests"

Action:
1. Fetch MRs from all projects using /api/v4/merge_requests?state=opened
2. Group by project
3. Output in Markdown table with project name, MR details, and links

User asks: "Create an issue in myproject about the login bug"

Action:
1. Load config.json
2. Find project ID for "myproject"
3. Ask for issue details if not provided (description, labels, assignee)
4. Create the issue via API
5. Confirm creation and show issue URL

User asks: "What's the status of the main branch in project-group/webapp?"

Action:
1. Find project by name/path
2. Fetch branch details for "main"
3. Show commit info, protection status
4. Optionally show recent commits or pipeline status

Notes

• All API calls should include the access token in the PRIVATE-TOKEN header
• Use proper SSL/TLS handling for internal GitLab instances with self-signed certificates
• Respect rate limits and implement exponential backoff if needed
• Cache project ID lookups when appropriate to avoid repeated API calls