CodeReviewAgent
An AI reviewer for GitLab merge requests that reads your repository, not just the diff.
One specialist agent per changed file, a real checkout of the branch under review,
and a comment pipeline built to post fewer, better findings.
Quickstart · How it works · Configuration · Analytics · Contributing
Why another AI reviewer?
Most AI reviewers see a diff and guess. Their most common false positives are exactly
the ones a diff produces: "this symbol is undefined" (it is defined in a file the diff
does not show), "this method is never implemented", "this variable is unused". Nobody
reads the tenth wrong comment.
CodeReviewAgent is built around the opposite assumptions:
- It reads the code. Every reviewer works over a checkout of the merge request's
source branch, pinned to the exact commit being reviewed, with
read_file, grep
and glob. "Is this defined anywhere?" becomes a question it can answer.
- Silence is a valid answer. A reviewer that finds nothing says so. Findings are
gated, ranked, de-duplicated and capped before anything reaches the merge request.
- Your conventions, not ours. Which files are reviewed, by whom, and under which
house rules is a YAML profile, plus optional instruction files that live in your repository.
What it posts
- Inline findings on the exact diff line, headed with a severity badge
(🔴 high · 🟠 medium), with an Apply suggestion button when the fix is concrete code.
- A review summary, once per merge request. It orients the human reviewer (what changed,
where to look) and does not repeat the findings.
- Labels:
ai-reviewed, plus a review effort::N/5 estimate of how hard the MR is for a human to review.
Re-running on a new push reviews only the commits since the last review, and never
re-posts a finding that is already on the merge request.
How it works
merge request ──► fetch diff (GitLab API) ──► shallow checkout of the source branch
│
review profile (YAML) ──► classify each changed file
│
┌───────────────────────────────┼───────────────────────────────┐
service reviewer sql reviewer test reviewer …
(read · grep · glob) (read · grep · glob) (read · grep · glob)
└───────────────────────────────┼───────────────────────────────┘
▼
in-diff gate ─► rank & purge false positives ─► restore severities ─► de-duplicate ─► cap
│
inline comments · summary · labels
- Classify. Each changed file is matched against the profile's
file_types rules
(a deterministic match on file names, no LLM). A file matching no rule is skipped.
Go files that embed SQL can additionally be routed to the SQL reviewer.
- Review. Every
(file, reviewer) pair becomes an independent agent with its own
context, pulled from a work queue by a pool of workers. Reviewers are read-only: they
can read and search the checkout, but writes are refused and there is no shell.
- Filter. Findings that don't land on a line of the diff are dropped. A ranking agent
purges compile-time claims (the code already builds), style nits and unsupported
opinions, then selects findings up to a budget. Duplicates of anything already on the
MR are removed.
- Post, with retries, a fallback to a general note when a line can't be anchored, and a
refusal to post any comment with no text in it.
Eleven reviewers ship built in: service_reviewer (technical quality), service_business_reviewer
(does the code do what the ticket asked), sql_reviewer, test_reviewer, e2e_reviewer
(browser end-to-end specs), typescript_reviewer,
html_reviewer, scss_reviewer, dataview_reviewer, pbook_reviewer (message catalogues)
and rules_reviewer (the .aid house rules the other reviewers read).
Quickstart
You need a GitLab personal access token with api scope, and a key for any
OpenAI-compatible LLM endpoint (OpenRouter works out of the box).
git clone https://github.com/systemgroup/codereviewagent.git
cd codereviewagent
cp .env.example .env # set DEFAULT_LLM_API_KEY, DEFAULT_LLM_MODEL, GITLAB_URL, GITLAB_TOKEN
docker build -t codereviewagent reviewer
docker run --rm --env-file .env codereviewagent \
python main.py --gitlab-mr "https://gitlab.example.com/group/project/-/merge_requests/42"
Run it on every merge request (GitLab CI)
Add a job to the project you want reviewed:
ai-review:
stage: test
image: ghcr.io/systemgroup/codereviewagent:latest # or your own build
variables:
GIT_STRATEGY: none # the reviewer makes its own checkout
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
script:
- cd /app && python main.py --gitlab-mr "$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID"
Put DEFAULT_LLM_API_KEY, DEFAULT_LLM_MODEL, GITLAB_URL and GITLAB_TOKEN in
Settings → CI/CD → Variables (masked). The token needs api scope, which also covers
the read-only clone.
Run the whole stack locally
docker compose up -d # reviewer web UI on :5000, analytics collector on :8000, PostgreSQL
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
