gitlab-api · diff
git:20260316.2d4c8cf to git:20260923.7852cb4
93 added, 56 removed. Audit A to A.
---
name: gitlab-api
description: Fetches and analyzes GitLab merge request (MR) comments, metadata, and review feedback using authenticated API calls. Capabilities include fetching comment threads, retrieving reviewer feedback, filtering unresolved discussions, and generating MR activity reports. Use when the user asks about GitLab MR comments, code review discussions, review feedback, approval status, troubleshooting review delays, or needs to fetch merge request metadata via the GitLab API.
---
# GitLab API Integration
Retrieve and analyze GitLab merge request comments and metadata using authenticated API calls.
+ ## Mindset
+
+ Every GitLab MR comment fetch is a **snapshot of a moving target**, not a stable record. Comments get edited, resolved, and deleted between when a review happens and when it's analyzed, and the GitLab API returns `200 OK` even when the payload inside is an error object — HTTP status alone does not mean "this data is valid." Treat every fetch as provisional: validate the shape of what came back before trusting it, and re-fetch rather than cache when the analysis is time-sensitive (an "unresolved discussion" report generated from an hour-old cache is actively misleading, not just stale).
+
+ The second load-bearing habit: `System` and `Type` are two independent axes, not one. `System: true/false` answers "who/what generated this" (bot vs human); `Type: DiffNote/comment` answers "where does this comment live" (inline on a diff line vs a general MR-level remark). A report that conflates them — e.g. treating all `DiffNote`s as human or all `comment`s as automated — will misclassify real feedback.
+
+ ## When to Use
+
+ - Fetching, filtering, or summarizing GitLab MR comment threads, reviewer feedback, or approval/discussion status via the API
+ - Building a script or report that needs to distinguish human review feedback from automated/bot comments, or inline code comments from general discussion
+ - Diagnosing why an MR API call fails (401/404, malformed URL, missing scope)
+
+ ## When NOT to Use
+
+ - GitLab CI/CD pipeline configuration or `.gitlab-ci.yml` authoring — unrelated to the MR comments API this skill wraps
+ - Working with GitLab issues, epics, or wikis — this skill's script and output format are scoped to merge request discussions only
+
## 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`
+ Fetches all comments from a GitLab merge request. Run it relative to this skill's own directory:
- **Usage:**
```bash
- .agents/skills/gitlab-api/scripts/get_mr_comments.sh <merge_request_url>
+ scripts/get_mr_comments.sh <merge_request_url>
```
**Example:**
```bash
# 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"
+ 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)
+ Read script source (`scripts/get_mr_comments.sh`, ~80 lines) when debugging unexpected output, extending for custom metadata, or understanding URL encoding. For basic usage, the examples above suffice.
- ## Common Workflows
+ ## Common Workflows and Error Handling
- ### Generate MR Review Summary
+ See [`references/workflows-and-error-handling.md`](references/workflows-and-error-handling.md) for the step-by-step review-summary and progress-tracking workflows, plus 401/404/200-with-error-body diagnosis.
- 1. Fetch and validate comments:
- ```bash
- 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
+ ## Anti-Patterns
- ### Track Review Progress
+ ### NEVER hardcode personal access tokens in scripts
- 1. Fetch and validate comments:
- ```bash
- 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
+ **WHY:** PATs stored in source code are exposed in git history even after removal and create a permanent security risk — anyone with repo access, at any point in the future, can recover a token committed once.
- ## Error Handling
+ ❌ BAD:
+ ```bash
+ GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx" # inline in a script committed to version control
+ ```
- **401 Unauthorized**: Token missing or invalid
- - Check `GITLAB_TOKEN` or `GITLAB_PAT` is set
- - Verify token has API read scope
+ ✅ GOOD:
+ ```bash
+ GITLAB_TOKEN="${GITLAB_TOKEN:?Set GITLAB_TOKEN with read_api 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
+ **Consequence:** A leaked PAT grants `read_api` access to every project the token owner can see, not just the one repo it was committed to.
- ## Anti-Patterns
+ ### NEVER assume a single page has all the results
- ### NEVER hardcode personal access tokens in scripts
+ **WHY:** The API always paginates; requesting `per_page=100` does not guarantee the result set fits on one page, and both under- and over-estimating the true count silently truncate downstream analysis.
- - **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.
+ ❌ BAD:
+ ```bash
+ curl "$API_URL/merge_requests?per_page=100" # assumes this is everything
+ ```
- ### NEVER paginate GitLab API results by hardcoding `?per_page=100` without loop handling
+ ✅ GOOD:
+ ```bash
+ page=1
+ while :; do
+ resp=$(curl -sD headers.txt "$API_URL/merge_requests?per_page=100&page=$page")
+ # process $resp
+ next=$(grep -i '^x-next-page:' headers.txt | tr -d '\r' | cut -d' ' -f2)
+ [ -z "$next" ] && break
+ page=$next
+ done
+ ```
- - **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.
+ **Consequence:** Reports built on the first page only silently omit older or later comments/MRs, and nothing in the response signals that truncation happened — it looks like a complete, valid result.
### 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.
+ **WHY:** The API enforces rate limits (typically 2000 req/min for REST); bulk operations without backoff must always check for `429` responses rather than assuming every request succeeds.
- ### NEVER use the `v3` API endpoint
+ ❌ BAD: firing parallel bulk API calls with no retry logic.
- - **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/...`
+ ✅ GOOD: check for `429` status codes and implement exponential backoff, honoring the `Retry-After` header when the API provides one.
+ **Consequence:** A burst of unthrottled calls gets throttled mid-run, and any call that doesn't check its own status code silently treats a `429` error body as if it were real data.
+
+ ### NEVER use the API `v3` endpoint path
+
+ **WHY:** GitLab removed API v3 in GitLab 11.0; all integrations must use `v4`.
+
+ ❌ BAD:
+ ```
+ https://gitlab.example.com/api/v3/projects/
+ ```
+
+ ✅ GOOD:
+ ```
+ https://gitlab.example.com/api/v4/projects/
+ ```
+
+ **Consequence:** `v3` endpoints return 404 or are silently redirected on current GitLab instances, producing confusing failures that look like an auth or URL problem rather than a versioning one.
+
## 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)
+ - Check `System` to exclude bot messages — it is independent of `Type`, so don't conflate the two axes (see Mindset)
+ - Use `jq` for JSON parsing; never grep on raw API JSON
+ - Validate responses before processing — the API can return `200 OK` with an error body
- 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
+ - Re-fetch for time-sensitive analysis — comments can be edited or deleted between fetches
+ - Handle UTC timestamps with proper timezone conversion when displaying to users in another zone
+
+ ## Eval Scenarios
+
+ - [Scenario 1: Generate MR review summary](evals/scenario-1/task.md)
+ - [Scenario 2: Monitor MR review activity](evals/scenario-2/task.md)
+ - [Scenario 3: Diagnostic tool for MR access issues](evals/scenario-3/task.md)
+ - [Scenario 4: Separate code review from discussion comments](evals/scenario-4/task.md)
+ - [Scenario 5: GitLab MR integration starter kit](evals/scenario-5/task.md)
+
+ ## References
+
+ | Topic | Reference | When to Use |
+ | --- | --- | --- |
+ | Step-by-step review-summary/progress-tracking workflows and 401/404/200-with-error-body diagnosis | [Workflows and Error Handling](references/workflows-and-error-handling.md) | Building a report/monitoring script, or diagnosing a failed API call |