Codex GitLab Merge Request Review Checklist

Originally published on IndieSeek.

Codex GitLab merge-request reviews: verify identity, webhooks, and diff coverage before automation

Quick answer

OpenAI released GitLab support for Codex cloud in beta on August 19, 2026. It can start tasks from GitLab issues or merge requests, respond to @codex review, and run automatic merge-request reviews. The feature is available on all ChatGPT plans, but the operational path is not one switch: the GitLab identity, webhook delivery, Codex project environment, review policy, and actual diff coverage are separate gates.

Start with one disposable repository and manual review. Do not enable automatic reviews until you can prove which identity posted the review, which commit was reviewed, which repository guidance applied, and whether GitLab exposed the complete diff. If GitLab omits a collapsed or oversized diff, treat the review as incomplete—not as a clean result.

Who this is for

This guide is for teams moving Codex code review from GitHub-style workflows into GitLab.com, GitLab Self-Managed, or GitLab Dedicated. It is especially useful when an administrator is deciding between project and group rollout, or when a reviewer also wants Codex to fix findings and push to the merge-request branch.

If your primary question is how to write repository-specific review instructions, compare the GitHub Copilot code-review setup guide. If you are deciding how much autonomy to grant after review, start with the Codex auto-review safety checklist.

What changed—and where the boundaries remain

Surface	Confirmed behavior	Rollout boundary
Availability	GitLab support is beta on all ChatGPT plans and runs in Codex cloud	Beta availability does not prove a workspace administrator has enabled the connector
GitLab.com	A user connects GitLab and creates a project environment to enable Codex reviews	Connection, environment, and webhook delivery are separate checks
Self-Managed / Dedicated	A workspace administrator publishes the connector template and configures a service account	Scope access to selected groups or projects; do not use a personal administrator identity as the steady-state reviewer
Event delivery	Project or eligible group webhooks deliver merge-request, note, and issue activity	Group activity supports reviews but does not create a project environment for code-writing tasks
Review policy	Manual @codex review and automatic triggers are supported	Manual and automatic review have different severity defaults and need separate acceptance tests
Review context	Codex reads the merge-request diff and applicable AGENTS.md rules	A collapsed or oversized diff that GitLab omits prevents a complete review

The key distinction is between identity, event delivery, execution authority, and review coverage. A green connector screen proves none of the other three.

Build the four-layer rollout matrix

Before changing a policy, write down one observable expectation for each layer.

Layer	Question	Evidence to retain	Fail-closed result
Identity	Which GitLab user or service account can read and post?	Account, selected groups/projects, role, token owner and expiry without the token value	Revoke or narrow access
Event path	Which project or group webhook delivers activity?	Recent delivery ID, event type, target project, HTTP result	No automatic review
Execution	Can Codex only review, or also edit, commit, and push?	Project-environment name, allowed repository, setup/network boundary	Keep fix tasks disabled
Coverage	Did Codex receive the current complete diff and correct rules?	MR head SHA, changed-file inventory, applicable AGENTS.md, review result	Require human review

This matrix prevents a common mistake: enabling a group webhook for reviews and assuming Codex can safely fix code across the group. OpenAI documents those as different capabilities. Review activity can be inherited from a group; writing or executing code requires a configured project environment.

A six-stage rollout

1. Freeze the test repository and reviewer identity

Choose one non-production repository with no sensitive secrets. Record whether it uses GitLab.com, Self-Managed, or Dedicated, plus the group, project, default branch, and rollout owner.

For Self-Managed or Dedicated, prefer a service account with Developer access only to the selected group or project. The documented connector token uses the api scope; that makes the selected resource boundary and token lifecycle especially important. Record the expiry and revocation owner, but never paste the token into the repository, article evidence, or an agent prompt.

2. Prove event delivery before judging review quality

Enable Codex activity for the test project and open a harmless merge request. In GitLab Webhooks → Recent events, verify that the merge-request event reached the configured destination. Then post @codex review and verify the note event is delivered.

For Self-Managed or Dedicated, confirm the supported GitLab version, signed webhook configuration, and SSL verification. If delivery fails, repair the event path first. Reconnecting models or rewriting AGENTS.md cannot fix a disabled webhook.

3. Start in manual, review-only mode

Keep automatic reviews off. Use @codex review on three bounded fixtures:

1. a small change containing one intentional, consequential defect;
2. a mechanical-only change that should not attract a high-severity finding;
3. a nested service change governed by a more specific AGENTS.md file.

Bind every observation to the merge-request head SHA. Codex review guidance should encode durable compatibility, data, or side-effect rules; deterministic formatting and lint checks belong in CI. Review rules guide the model, but do not replace tests, protected branches, or required human approvals.

4. Prove diff coverage, including the stop condition

Compare GitLab's changed-file list with the files and lines the review could access. Add one synthetic large-diff fixture in the disposable repository and observe whether GitLab collapses or omits content. Do not make the fixture contain real secrets or exploit code.

OpenAI explicitly states that Codex cannot complete a review when GitLab omits a collapsed or oversized diff. Your acceptance rule should therefore be:

complete diff + expected rules + current head SHA -> review may be considered
missing/collapsed/oversized diff                -> review incomplete; human review required

A missing review is visible. A confident “no findings” over an incomplete diff is the more dangerous failure.

5. Canary automatic triggers without duplicate review noise

After manual fixtures pass, enable automatic review for the single test repository. Choose one trigger—MR open, every push, or Smart Trigger (Experimental)—and record it. Push two commits in quick succession and verify which SHA each review covers, whether an older run is superseded, and whether duplicate discussions appear.

OpenAI's documented defaults differ: manually requested reviews may include P0, P1, and P2 findings, while automatic reviews focus on P0 and P1. Compare like with like before concluding that automatic review “missed” a lower-severity issue.

6. Add write authority only as a separate decision

If the workflow needs @codex fix, create a project environment for the one test project and define its setup, secrets, network access, and branch permissions. First ask Codex to make a harmless marker change, verify the commit and pipeline, and revert it. Keep merge rights and production deployment outside the canary.

Finally, disable automatic review, remove GitLab activity, and revoke or replace the service-account token in the test lane. Pass only if new events no longer start reviews, the old token no longer works, and the rollback owner can restore the approved configuration from a redacted record.

Rollout decision tree

Do you only need merge-request review?
  yes -> enable project/group activity; keep write environment absent
  no  -> create a project environment for each authorized project

Did the webhook deliver the current MR/note event?
  no  -> repair identity, webhook, version, signature, or SSL
  yes -> did Codex review the current head SHA with complete diff coverage?
           no  -> require human review; do not enable automatic review
           yes -> did manual fixtures produce useful, bounded findings?
                    no  -> narrow AGENTS.md rules and repeat
                    yes -> canary one automatic trigger in one repository

Does a fix require secrets, network, commit, or push access?
  yes -> treat it as a new authority grant with its own canaries
  no  -> keep review and write permissions separated anyway

Common mistakes

• Treating “connector connected” as proof that project events are delivered.
• Granting a personal administrator account when a project-scoped service account is enough.
• Assuming a group webhook creates the project environment required for fixes.
• Enabling automatic review everywhere before testing one manual repository.
• Comparing manual P2 findings with automatic P0/P1 defaults as if the policies were identical.
• Accepting “no findings” without recording the head SHA and complete-diff evidence.
• Putting formatting and lint instructions into AGENTS.md instead of deterministic CI.
• Saving a personal access token, webhook secret, or setup log in the repository.
• Letting a review bot merge or deploy during the first rollout canary.

Copyable acceptance record

date / owner / GitLab type and version:
workspace / connector / reviewer identity:
selected groups or projects / GitLab role / token expiry owner:
project or group webhook / recent delivery evidence:
project environment present? / setup / network / secret boundary:
review policy / trigger / repository override:
MR URL / head SHA / changed files / complete diff evidence:
root and nested AGENTS.md rules applied:
intentional defect result / mechanical-noise result:
collapsed-or-oversized-diff stop result:
automatic-review duplicate and stale-SHA result:
write canary or not applicable / pipeline / revert:
disable activity / revoke token / old credential result:
decision: blocked | manual-only | review-canary | write-canary | promote
next review date:

FAQ

Is Codex GitLab support generally available?

No. OpenAI labels it beta, although it is available across ChatGPT plans. Keep the feature maturity and your own rollout evidence separate.

Do GitLab reviews require a Codex project environment?

GitLab.com reviews require a project environment in the documented setup. For Self-Managed or Dedicated, group activity can enable reviews across eligible projects without creating project environments. Editing files, running commands, committing, pushing, or fixing findings still requires a project environment.

Should we enable review on every push?

Only after testing update bursts in one repository. Bind reviews to the head SHA, watch for duplicates or stale findings, and choose the trigger that matches your team's review cadence.

Can AGENTS.md replace branch protection or human approval?

No. It helps Codex apply repository-specific review guidance. Tests, branch protections, required approvals, ownership rules, and deployment controls remain independent gates.

Sources

• OpenAI release notes: GitLab support in Codex cloud
• OpenAI documentation: Review GitLab merge requests with Codex
• GitLab documentation: Webhooks
• GitLab documentation: Service accounts

Read the maintained original on IndieSeek.