Cloud review architecture
Every pull request event travels the same path.
Pull request event
-> queue with commit SHA
-> isolated review worker
-> diff and repository policy
-> Claude or GPT API
-> verifier and deduplicator
-> review comment store
-> Git provider review API
The worker has read-only access to the repository and needs only the diff, the selected files, the test commands and the policy text. A separate publisher, holding a short-lived token with the smallest review permission, posts the result. The API key lives in the CI secret store, never in the workflow file or the prompt. Each layer has one job:
| Layer | Rule |
|---|---|
| CI secret | Holds the codexkey key and hands it to the review job only |
| Queue | Limits parallel runs and repeated runs for one commit |
| Context | Passes the diff and the files it needs, leaves out .env, keys and data exports |
| Model | Uses a base route and escalates for a risky diff |
| Publication | Creates a draft, or a comment after the evidence filter |
| Observability | Records the model ID, spend, duration and the outcome of the check |
Model routes
| Review class | Candidate ID | Guard |
|---|---|---|
| Cross-module or security-sensitive | claude-opus-5-5 | Require evidence before publication |
| Routine TypeScript or Go diff | claude-sonnet-5 | Keep the rubric and fixture set current |
| Independent second opinion | gpt-6.1-sol | Mark findings by model ID |
| Narrow lint-style check | gpt-6-luna | Do not turn a weak result into a blocking review |
We checked the live codexkey catalog on October 4, 2026 and found these four IDs. A route can change when your evaluation changes, so read the current model details before a rollout.
For a routine diff, start with claude-sonnet-5 or gpt-6-sol. Write the escalation criteria as code, because hope is not a rule: database migrations, authorization changes, payments, external webhooks, data deletion. Only a diff that matches one of them gets a second pass on claude-opus-5-5 or gpt-6-astra.
After you sign up, create a separate CI key with a limit that matches the project budget. Review spend then shows up on its own line, apart from product traffic.
Duplicate events and runaway spend
Pull request systems can send several events for one commit. Build an idempotency key from the repository, the pull request number, the commit SHA and the review policy version, and store it before calling the model. If the key already exists, return the previous result.
Give every job a deadline. A stuck model request should move to a retry queue or a human review state, and it should not hold a worker and a pull request lock forever.
The limit on the CI key is the second line of defense. When a webhook loops or a bad config ships, spend stops at the limit and the rest of the balance survives.
Context limits and data policy
Start with the changed files, and add a module's interface or test only when the reviewer needs it. Strip secrets, customer records and credentials before the prompt is built. Keep the original diff in source control, and store a hash in the review log when full retention is not allowed.
A repository can contain instructions written by an attacker, so mark the diff as untrusted data. Review rules belong in a protected system prompt or a config file. A code comment can pose as policy, and the model may believe it.
Verification and publication
Ask for structured findings with a path, a line, a consequence, a reproduction and a fix. Check each one with a test, a source trace or a contract check, and discard what cannot be tied to a concrete failure mode.
Publish one review per commit, deduplicated by path, line and finding fingerprint. An uncertain finding becomes a non-blocking note or goes to a maintainer queue. An unverified model answer never changes the branch.
Observability that helps
Record the commit SHA, policy version, model ID, queue time, model latency, parse status, number of findings, number of verified findings and publication status. Keep enough to reproduce a result without copying private source into every log line.
Alert on queue age, repeated provider failures, malformed output and a sudden shift in the verified-finding rate. A model can return HTTP 200 and still break your contract.
Rollout plan
Switch the pipeline on for an internal repository first. Take recent closed pull requests where the real bugs are known and count precision: how many of the bot's findings point at an actual defect. If the bot produces generic advice, narrow the prompt, hand it the project rules and forbid any comment without a reproducible consequence.
Next, run the worker in report-only mode, as drafts, and compare its findings with human reviews over several releases. Block automatically only for categories with a low false-positive rate and a reproducible verifier. Keep a manual bypass for outages and false positives, with an audit record on every use.
After a model update, replay the fixture set before moving traffic to the new route. Keep the previous model ID available until the new route gives a stable review signal.
FAQ
What must never go into AI review?
Secrets, keys, production dumps and personal data, unless the processing is agreed. Filter files and redact before the model call.
How do I tell that the automation is useful?
Compare the time to the first useful remark, the share of confirmed findings and the cost per closed risk. Likes on comments do not replace checking the outcome.
Can cloud review run without storing source code?
Yes: keep a hash and the review result, and send the provider only the diff the model needs. Retention depends on your data policy and the provider's terms, so settle it before launch.
Which model should block a merge?
One that has passed your own verification fixtures, and only for findings with a reproducible consequence. A model name is not a merge policy.
How do I avoid duplicate review comments?
Use an idempotency key per job and a fingerprint per finding, and check the commit SHA before publishing.
Does a cloud worker need write access to the repository?
No. Give it read access to the files it needs and keep publication in a separate step with a narrowly scoped token.
Where do I compare Claude and GPT routes?
The AI review pipeline guide covers the stages, and the models documentation lists the current IDs.