Fix Codex Agent to use gpt-5.3-codex instead of deprecated gpt-5.1-codex

Jafar Soltanirequested to merge
fix/606775-codex-agent-gpt-5-3-codex into master

What does this MR do and why?

The Codex Agent by GitLab was configured to use gpt-5.1-codex, which OpenAI shut down on 2026-04-22 and which was subsequently removed from the AI Gateway. Every agent session fails immediately with {"detail":"Unsupported model"}.

This is the quick fix agreed in the issue discussion. It has two parts:

  1. Seeder (ee/lib/gitlab/ai/catalog/third_party_flows/seeder.rb) now uses gpt-5.3-codex, the only Codex model still registered in the AI Gateway models.yml. This covers instances that have not seeded yet.
  2. Post-deployment data migration updates the definition JSONB of existing Ai::Catalog::ItemVersion records in place. Already-seeded instances need this because Seeder#already_seeded? makes re-running gitlab:ai_catalog:seed_external_agents a no-op for them.

Documentation is also corrected: gpt-5.1-codex and gpt-5-codex are removed from the supported model list, and the copy-paste example now uses gpt-5.3-codex. Without this, a customer following the docs recreates the bug in their own agent.

Why the migration mutates a released version

Ai::Catalog::ItemVersion#validate_readonly treats released versions as immutable, so this migration deliberately bypasses the model layer. That is intentional: updating the existing versions in place means every consumer pinned to one of them is fixed without anyone having to select a new version in the UI. No audit event is emitted, since the change originates from a migration rather than a user action.

The migration updates every version of a matching item that references the shut-down model, not only the latest. The Codex Agent on GitLab.com is at version 1.5.0, and a project pinned to an earlier version is equally broken, so leaving older versions untouched would leave those projects failing.

Scope of the migration

The update is scoped to GitLab-maintained external agents: item_type = third_party_flow and verification_level = gitlab_maintained. Customer-authored definitions that reference the same model are left untouched, which matters because the documented example shipped gpt-5.1-codex. verification_level is a safe discriminator because only our own seeding code sets it, never user input.

The scope deliberately does not filter on project_id. The Codex Agent on GitLab.com (catalog item 2334) is scoped to the gitlab-org/gitlab project, while Gitlab::Ai::Catalog::ThirdPartyFlows::Seeder creates instance-level items with no project. Filtering on either shape would miss the other.

The definition is rewritten as text in a single pass, so both the parsed commands array (executed by Ai::FlowTriggers::RunService) and the yaml_definition string (rendered in the UI) are updated. A targeted substring replacement also preserves local edits: the definition on GitLab.com has diverged from the seeder, and it carries git config commands and prompt wording the seeder does not have. Regenerating the definition from the seeder would silently discard those.

down is a no-op. Restoring gpt-5.1-codex would re-break the agent, including on instances seeded after this deploy.

Raw SQL

UPDATE ai_catalog_item_versions AS versions
SET definition = replace(versions.definition::text, 'gpt-5.1-codex', 'gpt-5.3-codex')::jsonb,
    updated_at = NOW()
FROM ai_catalog_items AS items
WHERE items.id = versions.ai_catalog_item_id
  AND items.item_type = 3
  AND items.verification_level = 100
  AND versions.definition::text LIKE '%gpt-5.1-codex%'

Query plan: to be added from the db:gitlabcom-database-testing run. ai_catalog_item_versions is a small table per its database dictionary entry, and the expected number of affected rows on GitLab.com is the versions of catalog item 2334 that still reference the model.

Follow-up work

  • Backports to maintained versions are needed so already-seeded Self-managed and Dedicated instances on the hosted AI Gateway are repaired, and require the patch release process.
  • The long-term fix, sourcing the model configuration at run time instead of baking it in at seed time, is tracked in #607838.

References

Screenshots or screen recordings

Backend and documentation only.

How to set up and validate locally

  1. Seed the external agents: bundle exec rake gitlab:ai_catalog:seed_external_agents.
  2. Edit the seeded Codex ItemVersion definition back to gpt-5.1-codex to simulate an instance seeded before this fix.
  3. Run bundle exec rails db:migrate:post_deploy and confirm the definition, both commands and yaml_definition, now references gpt-5.3-codex.
  4. Create a project-level external agent that references gpt-5.1-codex and confirm the migration leaves it unchanged.
  5. Trigger a Codex Agent session and confirm it no longer fails with Unsupported model.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Jafar Soltani

Merge request reports