gitlab-code-review

GitLab Code Review

Perform a structured code review of the current branch's changes and post results to a GitLab merge request (in CI) or display them locally for preview.

Step 1: Review Code Changes

Review ALL commits in the branch since the base branch. Use git commands to inspect the changes — do NOT access remote APIs (e.g., glab commands).

IMPORTANT: In CI, always use $CI_MERGE_REQUEST_DIFF_BASE_SHA and $CI_COMMIT_SHA to define the diff range. Never use origin/main..HEAD in CI because the checkout may leave HEAD detached at the target branch tip, producing an empty diff. The CI variables point to the exact commits that define the MR diff. Fall back to origin/main..HEAD only for local runs.

# Set the diff range — CI variables are authoritative when present
if [ -n "$CI_MERGE_REQUEST_DIFF_BASE_SHA" ] && [ -n "$CI_COMMIT_SHA" ]; then
  BASE="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
  HEAD_REF="$CI_COMMIT_SHA"
else
  BASE="origin/main"  # adjust if default branch differs (e.g., master, develop)
  HEAD_REF="HEAD"
fi

Use $BASE and $HEAD_REF for all git commands:

git log --oneline ${BASE}..${HEAD_REF}
git diff ${BASE}..${HEAD_REF}

Only review the committed diff between branches. Do NOT run git status, do NOT report on untracked files, and do NOT include uncommitted working-tree changes in your review.

Review Guidelines

$ARGUMENTS

If no additional instructions were provided above, follow these defaults:

Provide constructive feedback that helps maintain code quality and follows project best practices. Be selective and focused: only comment on issues that genuinely matter. Do not comment for the sake of commenting. If the code is well-written and follows best practices, it is perfectly acceptable to return zero inline comments. Prioritize critical and major issues over minor stylistic preferences. Avoid repeating the same type of feedback across multiple locations — one representative comment is sufficient.

When referencing coding standards, security norms, best practices, or component-specific behavior, search for and cite the authoritative source (official documentation, RFCs, upstream references) to back up the claim.

Step 2: Produce Review JSON

Write your review output as a JSON file at /tmp/ai-review-output.json.

The JSON must be a valid object matching this schema exactly:

{
  "summary": "Brief overall assessment of the changes (2-4 sentences, markdown allowed inside this string)",
  "positive_aspects": ["List of good practices and well-implemented features"],
  "inline_comments": [
    {
      "file": "path/to/file (relative to repo root)",
      "line": 42,
      "severity": "critical|major|minor|suggestion",
      "comment": "Description of the issue and suggested fix (markdown allowed inside this string)"
    }
  ],
  "fix_prompt": "Optional: a copy-paste prompt to fix all issues found. Omit this field if there are no actionable fixes."
}

Inline comments rules

• ONLY comment on lines that appear in the diff (changed or added lines). Do NOT comment on unchanged lines.
• Use the line number as it appears in the NEW version of the file.
• file must be the path relative to the repository root (e.g., src/main.py, not /workspace/src/main.py).
• Severity levels:
  • critical: Security vulnerabilities, build-breaking changes
  • major: Significant logic errors, pattern violations
  • minor: Style issues, minor improvements
  • suggestion: Optional improvements for code quality
• Each comment should be self-contained and actionable.
• If there are no inline issues to report, use an empty array [].

Summary rules

• Keep it short (2-4 sentences). The inline comments carry the detail.
• Mention the overall quality and any critical concerns.

Positive aspects rules

• List 1-3 things done well. If nothing stands out, use an empty array [].

Fix prompt rules

• Omit this field entirely if there are no actionable fixes.

Step 3: Post Results

Run the review.py script from this skill's scripts/ directory. Execute it directly (not via python) to invoke uv via the shebang:

./scripts/review.py post /tmp/ai-review-output.json

The script auto-detects the platform (GitLab CI, GitHub, or local) and handles:

• JSON validation and chill-mode filtering (controlled by $CHILL_MODE env var)
• Deduplication against previous reviews (skips comments on unchanged code)
• Deleting previous AI review discussions on the MR (GitLab)
• Posting inline comments and a summary note to the MR (GitLab)
• Falling back to formatted terminal display when no CI platform is detected

If the script reports a JSON parse error, fix the JSON in /tmp/ai-review-output.json and re-run the command.

Step 4: Report Results

After the script completes successfully:

• CI: Confirm the review was posted to the merge request
• Local: The script displays results directly in the terminal
• Errors: Report any failures from the script output

Gotchas

• Line numbers in inline_comments must reference the NEW file version, not the old one; using old-side line numbers causes comments to land on the wrong line in GitLab.
• The JSON output must be strict JSON (no trailing commas, no comments). Invalid JSON will cause the posting script to fail.
• Running git status or reviewing uncommitted changes will produce false findings that are not part of the MR diff.

Environment Variables

The Python script reads these from the environment. In GitLab CI, most are set automatically — no manual configuration needed.

GitLab

Variable	Required for	Default	Description
GITLAB_API_TOKEN	CI/MR	—	GitLab Personal Access Token
CI_SERVER_URL	—	https://gitlab.com	GitLab server URL
CI_PROJECT_ID	CI/MR	—	GitLab project ID
CI_MERGE_REQUEST_IID	CI/MR	—	Merge request IID
CI_MERGE_REQUEST_DIFF_BASE_SHA	CI/MR	—	Base SHA for diff positioning
CI_COMMIT_SHA	CI/MR	—	Head commit SHA
CI_JOB_NAME	—	ai-review	Job name for summary footer
CI_JOB_URL	—	#	Job URL for summary footer

Common

Variable	Required for	Default	Description
CHILL_MODE	—	true	Filter out suggestion-level comments
VERBOSE	—	false	Show detailed API error responses