Codex with GitLab: @codex Reviews and Tasks in Codex Cloud (Beta)

Last updated: October 17, 2026

Since the 2026-08-19 changelog entry, Codex cloud can connect to a GitLab project, review merge requests when someone comments @codex review (or automatically), and run @codex tasks that push fixes back to the MR branch. It is in beta on all ChatGPT plans. The verdict: GitLab.com teams can be running reviews in a few minutes, while GitLab Self-Managed and Dedicated teams need a workspace admin, a service account, and GitLab 19.0+ signed webhooks - and that plumbing is where almost all of the setup effort goes.

This guide walks through both paths, the four settings and two identities that make the integration confusing at first, how to teach Codex your review rules, and how it compares with GitLab Duo's own reviewer.

Official Sources#

What shipped#

The changelog entry is short and specific. Verbatim:

GitLab support is available in beta on all ChatGPT plans. Connect a GitLab project to Codex cloud, create an environment for it, start tasks from issues or merge requests with @codex, and request one-off or automatic merge request reviews.

That breaks down into four capabilities:

• Connect a GitLab project to Codex cloud, on GitLab.com or on a Self-Managed or Dedicated instance.
• Create a cloud environment for that project, so Codex can check out the code, run setup commands, and push.
• Start tasks with @codex from merge request comments (and issue events, which the project webhook also delivers).
• Review merge requests, either on request with @codex review or automatically on MR open, on every push, or via the experimental Smart Trigger.

What the beta does not include matters just as much:

• The GitLab doc says GitHub-style repository controls in the desktop app, such as Create pull request, are not part of this beta. The integration runs in Codex cloud.
• The changelog notes: "Codex cannot complete a review when GitLab omits a collapsed or oversize diff." Very large generated files or lockfile churn can therefore stall a review.
• A managed workspace admin can disable the connector entirely.

Here is what happens when someone asks for a review:

%% title: @codex review on a GitLab MR
sequenceDiagram
    participant Dev
    participant GL as GitLab
    participant CX as Codex cloud
    participant ID as Review identity
    Dev->>GL: Comment @codex review
    GL->>CX: Signed note event via webhook
    CX->>GL: React with eyes
    CX->>CX: Read diff and AGENTS.md rules
    CX->>ID: Findings ready
    ID->>GL: Post discussions and notes

On Self-Managed and Dedicated, the "review identity" is the workspace service account described below. The docs describe the review as "a standard GitLab code review focused on serious issues" posted as discussions and notes, "just like a teammate would."

Four settings, two identities: how it fits together#

Most setup confusion comes from the fact that four separate settings each unlock a different part of the integration, and two of them are identities that act in GitLab on Codex's behalf. Understanding them up front saves a lot of webhook debugging later.

1. User OAuth (the GitLab plugin) - identity one. Each person connects their own GitLab account. Per the help center, the plugin "acts as your GitLab user" under the OAuth scopes you grant. It can read projects, repository trees, branches, commits, diffs, MRs, issues, discussions, pipelines, jobs and logs, and - depending on admin settings - create branches and commits, update MRs and issues, add notes, approve or merge MRs, and retry pipelines. Admins gate those actions with Role access, Configure actions and Configure approvals.
2. Workspace service account (Self-Managed and Dedicated only) - identity two. The app template article is explicit: "For Codex review writes on GitLab Self-Managed or GitLab Dedicated, the workspace-managed service-account token determines the identity and projects where Codex can comment or react."
3. Webhook activity. A project webhook (or, on Self-Managed and Dedicated, a group webhook) delivers merge request, comment and issue events to Codex. Without it, @codex comments go nowhere.
4. Project environment. A Codex cloud environment for the project. It is required for any coding task (@codex fix ...), for reviews that depend on secrets or setup commands, and - on GitLab.com - for reviews at all.

%% title: What each GitLab setting unlocks
flowchart LR
    A[User OAuth app] --> A1[Read and act in chats]
    B[Service account] --> B1[Post reviews and reactions]
    C[Project webhook] --> C1[MR, note, issue events]
    D[Group webhook] --> D1[Reviews only]
    E[Project environment] --> E1["@codex fix and push"]
    C1 --> R[Codex cloud]
    D1 --> R
    B1 --> R
    E1 --> R

The doc's troubleshooting section summarizes the most common trap in one line: "activity and service-account access are separate."

Prerequisites#

• A ChatGPT plan, and ChatGPT sign-in. The beta is on all ChatGPT plans. OpenAI's authentication doc says that with API key sign-in, "some features that rely on ChatGPT workspace access or cloud services are limited or unavailable," and the feature availability table lists Codex cloud as not available with an API key. Since this integration runs in Codex cloud, sign in with your ChatGPT account. The Codex usage limits and pricing breakdown covers how sign-in method affects what you get.
• GitLab.com, or GitLab Self-Managed or Dedicated 19.0 or newer for webhook activity. GitLab 19.0 (released May 21, 2026) added HMAC signing tokens for webhooks in all tiers, following the Standard Webhooks spec. GitLab's stated reason is that the older X-Gitlab-Token header "sends a static secret in plain text."
• Maintainer or Owner on the project (or admin, or a custom role that can administer project webhooks) to create the project webhook.
• For group-wide activity: the connected user must be a group Owner, and group webhooks need GitLab Premium or Ultimate plus 19.0+.
• For Self-Managed or Dedicated: a ChatGPT workspace admin or owner, plus someone in GitLab who can create the OAuth application (group Owner for a group-owned app, instance admin for an instance-wide app). Creating the service account through Codex needs GitLab instance admin access.
• Optional: an AGENTS.md file if you want repository-specific review guidance.

Steps: GitLab.com#

1. Connect GitLab in ChatGPT. Open ChatGPT, go to the Plugin directory, search for GitLab, select Install Plugin, then Connect, and authorize ChatGPT in GitLab if prompted. To undo it later: Settings > Plugins > GitLab > Uninstall. Then connect your GitLab account in Codex.
2. Create a project environment. In Codex Cloud > Settings > Environments, choose the GitLab project and create an environment. While creating it, turn on Enable Codex activity from GitLab. This installs the project webhook for merge request, comment and issue events. On GitLab.com, this environment is also what enables reviews.
3. Set the review policy. Open Codex review settings for GitLab, choose the repository, and turn on Automatic review under Review code. Review picks whose MRs get reviewed. Trigger picks when: On MR open, On every push, or Smart Trigger (Experimental). Repository settings can override personal defaults.
4. Test it. Open a small test MR and comment @codex review. Codex should react with the eyes emoji and then post its findings.

If you only want on-demand reviews, skip the automatic review toggle in step 3 and rely on @codex review comments.

Steps: Self-Managed and Dedicated (admin path)#

This path has more moving parts because your instance, not OpenAI, owns the OAuth application, and because review writes run as a dedicated service account.

1. Start the app template in ChatGPT. Switch to the right workspace, go to Workspace settings > Apps, find GitLab in Directory, open the GitLab Self-Managed app template, and select Enable. Enter a name, description and the hostname only (for example gitlab.example.com - no https://, port, path, and never gitlab.com). Copy the exact Redirect URI shown, in the form https://chatgpt.com/connector/oauth/<redirect_id>. Do not add a trailing slash or edit it.
2. Create the OAuth application in GitLab. Use Admin > Applications for an instance-wide app or the group's Settings > Applications for a group-owned one. Paste the Redirect URI, keep Confidential enabled, and select the api, write_repository and openid scopes. For instance-wide apps, GitLab recommends Trusted, which skips the user authorization prompt. Save and copy the Application ID and Secret.
3. Finish and publish the draft. Back in ChatGPT, paste the Application ID into OAuth client ID and the Secret into OAuth client secret, select Create draft, then review Role access, Configure actions and Configure approvals. Select Publish. A draft is not visible to members until it is published.
4. Configure the service account. In Codex Cloud > Settings > Connectors, select the app for your host, then either:
   • Set up service account > Create a service account. Choose Selected groups (Developer access inherited by projects and subgroups) or Selected projects only. Codex creates a "ChatGPT Codex Connector" service account with a personal access token that has the api scope.
   • Use an existing service account. In GitLab, grant the account Developer access only where Codex should operate, then create a PAT with the api scope and an expiration date at least 30 days away. Paste it and select Save token. The token is encrypted on save and never shown again.
5. Enable activity. Either create a project environment with Enable Codex activity from GitLab turned on, or open Environments > GitLab activity > Manage groups to install a group webhook covering a group and its subgroups. Descendant projects inherit an ancestor group's coverage.
6. Check the feature flag on 19.0. On Self-Managed 19.0, confirm the webhook_signing_token feature flag is enabled. It is on by default and was removed in 19.1.
7. Have each reviewer connect. Users install the GitLab plugin from the Plugin directory or Settings > Plugins, select Connect, and pick the Self-Managed app if the workspace has more than one GitLab app.

%% title: Self-Managed setup order
flowchart TB
    subgraph Admin[Workspace and GitLab admins]
        S1[Enable app template] --> S2[Create GitLab OAuth app]
        S2 --> S3[Create draft and publish]
        S3 --> S4[Configure service account]
        S4 --> S5[Enable project or group activity]
        S5 --> S6[Check 19.0 signing flag]
    end
    subgraph Team[Developers]
        U1[Install and connect plugin] --> U2["Comment @codex review"]
    end
    S6 --> U1

The order matters. Codex "cannot respond to GitLab activity until a valid token is configured," so a perfectly installed webhook with no service account produces silence rather than an error.

Using it day to day#

Once activity is flowing, everything happens in MR comments.

Request a review:

@codex review

Give a one-off focus for this review only:

@codex review for issues in the database migration

Ask Codex to act on its own finding:

@codex fix the P1 issue

Hand it any other task in the MR's context:

@codex fix the CI failures

A few behaviors worth knowing:

• Severity defaults differ by trigger. Manually requested reviews can include P0, P1 and P2 findings. Automatic reviews focus on P0 and P1. That is a sensible split: when you ask, you get more; when it runs on every MR, it stays quiet unless something is serious.
• Anything other than review becomes a task. Per the docs, mentioning @codex with anything other than review starts a legacy cloud chat with the merge request as context.
• Fixes need an environment and permission. Codex "can push a fix back to the branch when it has permission to do so." Group activity alone supports reviews but cannot run coding tasks.

Because coding tasks run in a cloud environment that may have network access and secrets, apply the same hardening you would for any Codex cloud task. The Codex cloud security playbook covers internet access settings and domain allowlists.

Teach it your rules with AGENTS.md#

Codex searches the repository for AGENTS.md files and follows a ## Code Review Rules section. This is the documented example from the GitLab doc:

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Scoping works by directory. Put repository-wide rules in the root AGENTS.md and service-specific rules in a nested file such as services/experiment_reporting/AGENTS.md. Codex applies the root file plus the more specific guidance that covers each changed file, so unrelated changes do not carry irrelevant context.

OpenAI's guidance for writing them is worth following closely:

• Start with two or three concise rules that encode checks reviewers often explain.
• Describe the consequential, repository-specific behavior to flag and why it matters.
• State the safe path or exception, so Codex can tell a real issue from expected behavior.
• Keep formatting, lint and other deterministic checks in CI, not in review rules.

The docs also say plainly that rules "don't replace tests, branch protections, or required approvals." If your existing AGENTS.md is already long, the AGENTS.md configuration smells catalog is a good pass before you add review rules on top. A useful side effect for mixed shops: the same ## Code Review Rules section is read whether the repository lives on GitHub or GitLab.

Verify it works#

The quickest check is in GitLab itself: open the project's Settings > Webhooks, find the Codex hook, and look at Recent events. You want successful merge request and note deliveries after you comment @codex review.

For a scripted check, the GitLab project webhooks API lists hooks and the fields that matter here. This is a documented endpoint, shown as a reference rather than tested output:

curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.example.com/api/v4/projects/<project_id>/hooks"

On the Codex hook, look for:

• "signing_token_present": true - the hook is signed (GitLab never returns the token itself).
• "enable_ssl_verification": true
• "merge_requests_events": true, "note_events": true and "issues_events": true

Group hooks expose the same fields under /groups/:id/hooks (group webhooks API). The API also offers a per-hook events listing for the past seven days, filterable by successful, client_failure and server_failure, which is handy when a hook works intermittently.

Gotchas and limits#

Two docs, two meanings of "code review." The help center article says: "GitLab cloud code reviews are not available. Connecting GitLab or opening a merge request in Code Review does not enable automatic cloud reviews." That reads like a contradiction, but it refers to the Code Review feature in the app (opening an MR there). The Code Review doc clarifies: "GitLab merge request support in Code Review is in preview. To trigger cloud reviews from GitLab with @codex review or automatic merge request reviews, see Review GitLab merge requests with Codex." In short: connecting the plugin is not enough; webhook activity is what turns on cloud reviews.

Collapsed or oversize diffs block reviews. If GitLab omits the diff, Codex cannot complete the review. Keep generated files out of MRs or split large changes.

Group activity does not create environments. A group webhook gives you reviews across many projects, but @codex fix still needs a project environment per project.

Service account access is separate from user access. On Self-Managed and Dedicated, the connected user having Developer access is not enough - the service account needs Developer access to the project or a parent group to post reviews and reactions.

Plan for token rotation. Existing-account PATs need an expiration at least 30 days out. When the token expires, Codex goes silent. Admins can revoke and regenerate a Codex-created account's token, or replace a saved token, in Connectors settings.

Auto-disabled hooks. GitLab can disable a hook automatically after repeated failures. The troubleshooting list says to repair hooks that were disabled this way.

Admins can switch it off. A managed workspace admin can disable the connector, and Self-Managed admins decide which plugin actions are enabled and which need approval.

Data controls follow your plan. Per the help center, business offerings (ChatGPT Business, Enterprise, Edu, API) are not used for training by default; individual plans may be if "Improve the model for everyone" is on. GitLab content follows the same workspace data controls.

It is a beta. Expect UI labels and behavior to move. The Smart Trigger option is explicitly marked experimental.

Codex for GitLab vs GitLab Duo Code Review#

The closest alternative is GitLab's own reviewer. GitLab documents two flavors: the agentic Code Review Flow (no add-on, uses GitLab Credits) and the non-agentic GitLab Duo Code Review (requires GitLab Duo Enterprise). Both use @GitLabDuo as the reviewer.

Where Duo is stronger: it is native to GitLab, needs no external connector or service account, and, with the opt-in approve/request-changes setting turned on, the Code Review Flow can request changes that block a merge just as a human reviewer would. GitLab also notes the Code Review Flow uses earlier Duo threads to evaluate follow-up changes, and from 19.5 it re-reviews automatically when a push changes the diff.

Where Codex is stronger: if your team already uses Codex on GitHub, in the CLI, or in the IDE, the same AGENTS.md rules and the same review behavior now carry over to GitLab, and review usage draws on your ChatGPT plan rather than a separate GitLab credit pool or seat add-on.

%% title: Which reviewer fits
flowchart TD
    Q1{Already on Duo Enterprise or Credits?} -->|Yes| Q2{Need merge-blocking reviews?}
    Q2 -->|Yes| DUO[GitLab Duo]
    Q2 -->|No| Q3
    Q1 -->|No| Q3{Using Codex on GitHub or CLI too?}
    Q3 -->|Yes| Q4{Self-Managed below 19.0?}
    Q3 -->|No| EITHER[Trial both on one project]
    Q4 -->|Yes| UPG[Upgrade GitLab or use Duo]
    Q4 -->|No| CODEX[Codex for GitLab]

Nothing stops you from running both on a pilot project for a couple of weeks and comparing signal-to-noise on real MRs. If you are weighing third-party reviewers like CodeRabbit, DeepSource or Greptile, which also support GitLab, see the best AI code review tools roundup. And for context on timing: GitHub's GitLab migration tooling went GA in August, but teams that prefer to stay on GitLab no longer have to move to get Codex review.

FAQ#

Is Codex GitLab support available on ChatGPT Free?#

The changelog says the beta is available "on all ChatGPT plans." The requirement is signing in to Codex with a ChatGPT account: OpenAI's feature availability table lists Codex cloud as not available with API key sign-in, and this integration runs in Codex cloud.

Does it work with GitLab Self-Managed?#

Yes, for Self-Managed and Dedicated. A workspace admin publishes an app from the GitLab Self-Managed app template using your own GitLab OAuth application (scopes api, write_repository, openid), configures a service account with an api-scoped token, and enables project or group activity. Webhook activity requires GitLab 19.0 or later.

Why didn't Codex react to @codex review?#

Work through the documented checklist: confirm the right GitLab app and project environment are selected; check Webhooks > Recent events for successful merge request and note deliveries; on Self-Managed, confirm the hook is signed, SSL verification is on, and the instance is 19.0+ (with the webhook_signing_token flag on 19.0); confirm the service-account token is active with the api scope; and confirm the service account itself has Developer access to the project.

Can Codex push fixes to my merge request?#

Yes, if the project has a configured Codex cloud environment and Codex has permission to push. Comment something like @codex fix the P1 issue. Group-level activity alone supports reviews but cannot run coding tasks.

How is this different from GitLab Duo Code Review?#

Duo is GitLab-native, billed through GitLab Credits or a Duo Enterprise seat, configured with .gitlab/duo/mr-review-instructions.yaml, and, when the opt-in "GitLab Duo can approve and request changes" setting is on, its Code Review Flow can request changes that block merges (its approvals do not count toward required approvals). Codex is billed through your ChatGPT plan, reads review rules from AGENTS.md, posts discussions and notes, and reuses the same setup across GitHub and GitLab.

Sources#

• OpenAI Codex changelog - https://developers.openai.com/codex/changelog
• Review GitLab merge requests with Codex - https://learn.chatgpt.com/docs/third-party/gitlab
• Codex GitHub integration - https://learn.chatgpt.com/docs/third-party/github
• Codex Code Review - https://learn.chatgpt.com/docs/code-review
• Codex authentication - https://learn.chatgpt.com/docs/auth
• Codex pricing and feature availability - https://learn.chatgpt.com/docs/pricing#feature-availability
• Connecting GitLab to ChatGPT and Codex - https://help.openai.com/en/articles/20001486-connecting-gitlab-to-chatgpt-and-codex
• Setting up the GitLab Self-Managed app template for ChatGPT and Codex - https://help.openai.com/en/articles/20001487-setting-up-the-gitlab-self-managed-app-template-for-chatgpt-and-codex
• GitLab 19.0 release notes - https://docs.gitlab.com/releases/19/gitlab-19-0-released/
• GitLab webhooks - https://docs.gitlab.com/user/project/integrations/webhooks/
• GitLab project webhooks API - https://docs.gitlab.com/api/project_webhooks/
• GitLab group webhooks API - https://docs.gitlab.com/api/group_webhooks/
• GitLab Duo in merge requests - https://docs.gitlab.com/user/project/merge_requests/duo_in_merge_requests/
• GitLab Code Review Flow - https://docs.gitlab.com/user/duo_agent_platform/flows/foundational_flows/code_review/
• GitLab Duo review instructions - https://docs.gitlab.com/user/gitlab_duo/customize_duo/review_instructions/

Continue Reading#

• OpenAI Codex Cloud Security Playbook 2026 - harden the cloud environments that @codex fix tasks run in.
• Codex SDK vs CLI vs GitHub Action - the GitHub-side options if you run Codex across both forges.
• Best AI Code Review Tools 2026 - the wider reviewer market, including other tools with GitLab support.