GitLab Code Reviewer

intent

performs structured code review on gitlab merge requests by analyzing diffs, identifying issues across java/spring boot, mongodb, postgresql, react, and typescript codebases, and posting inline comments back to the mr. use when reviewing mrs for code quality, security, performance, maintainability, or design patterns. triggers on requests like "review this mr", "check this merge request", "post review comments to gitlab", "analyze the diff at a gitlab url", or "do a code review for a merge request url".

inputs

gitlab credentials file (~/.openclaw/credentials/gitlab.json)

{
  "token": "glpat-xxx",
  "host": "https://gitlab.com",
  "ignore_patterns": ["*.min.js", "*.lock", "forms/*.json"]
}

required gitlab api token scopes:

• api , required for posting inline comments and fetching diffs
• read_api , sufficient for analysis only, no comment posting

external connection: gitlab api

• endpoint: https://gitlab.com/api/v4 (or custom host from credentials)
• authentication: bearer token in authorization: bearer glpat-xxx header
• rate limits: 600 requests/minute (unauthenticated: 300/minute). token check and diff fetch each consume 1-2 requests; posting comments consume 1 request per comment. plan for ~5-10 api calls per mr analysis.

reference files:

• references/review-guidelines.md , review rules, severity definitions, comment format templates for java, mongodb, postgresql, react, typescript
• scripts/gitlab_client.py , cli wrapper for gitlab api
• scripts/post_comments.py , comment posting script
• scripts/ignore_matcher.py , file filtering logic

user provides:

• gitlab mr url (e.g., https://gitlab.com/org/repo/-/merge_requests/123)

procedure

step 1: check token scope

run token scope validation before any analysis to determine if inline comments can be posted.

input: gitlab credentials from ~/.openclaw/credentials/gitlab.json, mr url

command:

python scripts/gitlab_client.py check-token <mr_url>

output: json response with fields "can_write": true/false, "token_valid": true/false, "scopes": [...]

action: if can_write is false, inform user that the token lacks api scope and skip step 6 entirely. do not proceed to analysis and fail later at comment posting. continue with analysis only if token_valid is true.

step 2: fetch mr metadata and unified diff

input: mr url, valid gitlab token

commands:

python scripts/gitlab_client.py fetch-mr <mr_url>
python scripts/gitlab_client.py fetch-diff <mr_url>

output from fetch-mr: json object with id, iid, title, source_branch, target_branch, author, created_at

output from fetch-diff: json array of file objects. each file object contains:

• new_path (string) , target file path
• old_path (string) , source file path (null for new files)
• diff (string) , unified diff text
• new_file (boolean)
• deleted_file (boolean)
• renamed_file (boolean)

fallback: if /diffs endpoint returns http 500 (common on self-hosted gitlab), gitlab_client.py automatically retries via /changes endpoint. no manual intervention required.

step 3: filter files by ignore patterns

input: all diffs from step 2, ignore patterns from credentials file (or defaults)

script:

from ignore_matcher import filter_diffs
reviewable = filter_diffs(all_diffs)

default ignore patterns (always applied):

• *.min.js, *.min.css, *.lock, package-lock.json, pnpm-lock.yaml, forms/*.json
• binary extensions: .png, .jpg, .gif, .jar, .class, .o, .so, .map, etc.

output: filtered list of file diffs, excluding ignored files

edge case: if filtering removes all files, skip analysis and report "no reviewable files in this mr" to user.

step 4: analyze diffs by file

input: reviewable diffs from step 3, review guidelines from references/review-guidelines.md

scope: analyze only added and removed lines in the diff. do not comment on unchanged context lines.

focus areas by tech stack:

• java / spring boot , clean code principles, solid design, transaction boundaries, lazy loading, n+1 queries
• mongodb , query correctness, index coverage, atomicity, document structure
• postgresql , sql correctness, isolation levels, index usage, schema migrations
• react / typescript , hooks correctness (dependency arrays, stale closures), type safety, xss vulnerabilities, prop drilling

large diff handling: process file-by-file and aggregate results. deduplicate similar findings across files before final output.

output: structured findings grouped by severity (critical, major, minor) with file path, line number, issue description, and remediation suggestion.

step 5: aggregate review summary and decision

input: all findings from step 4, mr metadata from step 2

format:

## Code Review ,  <MR title> (<source_branch> → <target_branch>)

### critical
- `UserService.java:42` ,  transaction wraps http call; holds db lock during network i/o.

### major
- `OrderRepository.java:87` ,  n+1 query: `findRolesByUserId` called in loop. use batch query.

### minor
- `PaymentDto.java:15` ,  field name `val` lacks clarity.

## decision: <needs changes | pass | reject>

decision logic:

• pass: zero critical and zero major findings
• needs changes: one or more major findings, zero critical findings
• reject: one or more critical findings

output: formatted review summary as text or markdown

step 6: post inline comments to gitlab (conditional)

prerequisite: can_write from step 1 must be true. skip this entire step if false.

input: review findings from step 4, mr url, gitlab token

substep 6a: write comment payload to temp file

write all findings to a json file. never use shell -c with inline comment bodies due to escaping issues with backticks and special chars.

file format: /tmp/mr_comments_<timestamp>.json

[
  {
    "file_path": "src/main/UserService.java",
    "line": 42,
    "body": "[CRITICAL] transaction wraps http call; holds db lock during network i/o.\n\nthis code acquires a db transaction before making an http request. if the request times out or fails, the transaction remains open, blocking other queries.\n\nsuggestion:\n```java\nUser user = userService.fetch();\ntry (Transaction tx = db.begin()) {\n  tx.update(user);\n}\n```"
  },
  {
    "file_path": "src/repository/OrderRepository.java",
    "line": 87,
    "body": "[MAJOR] n+1 query detected.\n\nfor each order in a loop, the code calls `findRolesByUserId`, which executes a separate query. with 1000 orders, this becomes 1001 queries.\n\nsuggestion:\n```java\nList<Order> orders = repo.findAllWithRoles();\n```"
  }
]

line number calculation from diff hunk header:

given a hunk header @@ -375,6 +375,8 @@:

• lines after + marker are new additions. count from the starting line (375 in this case).
• for an added line on the 3rd position in the hunk, use line 375 + 2 = 377.
• for deleted lines, use the line number from the old file range (the -X number).

example:

@@ -375,6 +375,8 @@
     unchanged line          → line 375
     unchanged line          → line 376
     unchanged line          → line 377
+    added line              → line 378  (use this)
+    added line              → line 379

substep 6b: post comments via gitlab api

command:

python scripts/post_comments.py <mr_url> /tmp/mr_comments_<timestamp>.json

output: json response with status for each comment. on success, returns array of posted comment ids and discussion urls.

error handling:

• http 403 insufficient_scope , script stops immediately and prints fix instruction (add api scope to token). do not retry.
• http 404 line not in diff , log error and continue posting remaining comments.
• http 429 rate limit , script backs off exponentially and retries. if still rate limited after 3 retries, report to user.
• network timeout after 30 seconds , log timeout and ask user to retry.

constraints:

• do not auto-approve the mr.
• do not add labels or trigger pipelines.
• only post comment-type discussions. do not call approval api endpoints.

decision points

decision: can token write to gitlab?

• if check-token returns can_write: true → proceed with steps 1-6 including comment posting.
• if can_write: false → report to user that token lacks api scope, complete steps 1-5 (analysis and summary), skip step 6 entirely.

decision: are there reviewable files?

• if filtering (step 3) removes all files → report "no reviewable files in this mr" and terminate.
• if at least one file remains → proceed with analysis.

decision: what is the review decision?

• if critical findings exist → decision is "reject".
• else if major findings exist → decision is "needs changes".
• else → decision is "pass".

decision: should we retry failed api calls?

• http 500 on /diffs endpoint → automatically retry via /changes (handled by gitlab_client.py).
• http 429 rate limit → back off exponentially, retry up to 3 times.
• http 403 insufficient_scope → stop immediately, do not retry.
• network timeout → log and ask user to retry manually.

output contract

success output structure:

1. token validation result (json)

   • fields: token_valid (boolean), can_write (boolean), scopes (array of strings)

2. mr metadata (json)

   • fields: id, iid, title, source_branch, target_branch, author, created_at

3. filtered diff files (json array)

   • each file: new_path, old_path, diff (string)

4. review summary (markdown or text)

   • sections: critical, major, minor (each with file path and line number)
   • final section: decision (reject / needs changes / pass)

5. comment posting result (json array, only if step 6 executed)

   • each entry: file_path, line, status (success/failed), discussion_url (on success), error_message (on failure)

6. no source code logged or persisted. all analysis remains in memory or in temp json files that are deleted after posting.

outcome signal

user knows the skill worked when:

1. token validated , terminal output shows "token_valid": true and "can_write": true (or true/false if posting is skipped).

2. diff fetched and files filtered , terminal or log shows count of reviewable files and total lines of code reviewed.

3. review summary displayed , user sees formatted markdown output with critical, major, and minor findings grouped by file and line number, plus final decision (reject/needs changes/pass).

4. inline comments posted to gitlab (if applicable) , user can navigate to the mr in gitlab and see new discussion threads on the affected lines. each comment includes the severity tag (critical/major/minor), explanation, and code suggestion. discussion urls are printed to terminal after posting completes.

5. errors reported clearly , if token lacks scope, files cannot be fetched, or api errors occur, user sees explicit error message with actionable fix (e.g., "add api scope to gitlab token" or "retry in 60 seconds due to rate limit").

6. temp files cleaned up , /tmp/mr_comments_*.json files are deleted after posting to prevent credential/code leaks.

---

credits: original skill from clawhub. enriched per implexa standards with explicit decision points, edge case handling, api rate limiting, and line number calculation guidance.