GitLab API Integration

Retrieve and analyze GitLab merge request comments and metadata using authenticated API calls.

Prerequisites

• Set GITLAB_TOKEN or GITLAB_PAT with read_api scope
• Requires: curl, jq

Available Scripts

get_mr_comments.sh

Fetches all comments from a GitLab merge request.

Location: .agents/skills/gitlab-api/scripts/get_mr_comments.sh

Usage:

.agents/skills/gitlab-api/scripts/get_mr_comments.sh <merge_request_url>

Example:

# Prerequisites assumed: GITLAB_TOKEN with read_api scope
.agents/skills/gitlab-api/scripts/get_mr_comments.sh "https://gitlab.com/your-group/your-project/-/merge_requests/123"

Output Format:

---
Author: Name (@username)
Date: ISO8601 timestamp (UTC)
Type: DiffNote|comment
System: true|false

Comment body text

• System: true — automated/system-generated message; System: false — human comment
• Type: DiffNote — inline code review comment; Type: comment — general MR comment
• Timestamps are UTC in ISO8601 format

Exit Codes:

• 0: Success
• 1: Invalid URL format, missing token, or API error

When to Examine Script Internals:

Read script source when debugging unexpected output, extending for custom metadata, or understanding URL encoding. For basic usage, the examples above suffice.

Script location: .agents/skills/gitlab-api/scripts/get_mr_comments.sh (~80 lines)

Common Workflows

Generate MR Review Summary

1. Fetch and validate comments:

   output=$(.agents/skills/gitlab-api/scripts/get_mr_comments.sh "$MR_URL")
   echo "$output" | grep -q "Author:" || { echo "Invalid response — check token and URL"; exit 1; }

2. Filter by System: false to exclude automated messages
3. Group by author, extract action items and feedback themes
4. Generate summary report

Track Review Progress

1. Fetch and validate comments:

   output=$(.agents/skills/gitlab-api/scripts/get_mr_comments.sh "$MR_URL")
   [ -n "$output" ] && echo "$output" | grep -q "Date:" || { echo "Empty or malformed response — check credentials"; exit 1; }

2. Compare timestamps to identify recent activity
3. Flag unresolved DiffNotes and report on response times

Error Handling

401 Unauthorized: Token missing or invalid

• Check GITLAB_TOKEN or GITLAB_PAT is set
• Verify token has API read scope

404 Project Not Found: Invalid project path

• Confirm URL format: https://gitlab.com/group/project/-/merge_requests/ID
• Check token has access to the project

Anti-Patterns

NEVER hardcode personal access tokens in scripts

• WHY: PATs stored in source code are exposed in git history even after removal and create a permanent security risk.
• BAD: GITLAB_TOKEN="glpat-xxxx" inline in a script committed to version control.
• GOOD: Read from environment variables ($GITLAB_TOKEN) or a secrets manager; document the required scope in README.

NEVER paginate GitLab API results by hardcoding ?per_page=100 without loop handling

• WHY: The API may have fewer results than the page size, or more results than one page; both cases require checking the X-Next-Page response header.
• BAD: curl .../merge_requests?per_page=100 assuming this returns all MRs.
• GOOD: Loop until X-Next-Page is empty: check the header in each response and fetch the next page.

NEVER call the GitLab API without respecting rate limits

• WHY: The API enforces rate limits (typically 2000 req/min for REST); bulk operations without backoff will receive 429 Too Many Requests responses.
• BAD: Parallel bulk API calls without retry logic.
• GOOD: Check for 429 status codes and implement exponential backoff; use the Retry-After header when provided.

NEVER use the v3 API endpoint

• WHY: GitLab removed API v3 in GitLab 11.0; all integrations must use v4.
• BAD: https://gitlab.com/api/v3/projects/...
• GOOD: https://gitlab.com/api/v4/projects/...

Critical Pitfalls

• Check System field to exclude bot messages
• Use jq for JSON parsing, never grep on raw API JSON
• Validate responses before processing (API returns 200 OK with errors)
• URL-encode nested groups (%2F for / in project paths)
• Re-fetch for time-sensitive analysis (comments can be edited/deleted)
• Respect Type distinction: DiffNote (code-level) vs comment (architectural)
• Handle UTC timestamps with proper timezone conversion