Skip to content

Product Requirements – Claude Code and OpenAI Codex CLI Integration for GitLab CI/CD

Executive Summary

GitLab will enable teams to delegate routine development work to AI assistants by mentioning @claude or @codex inside an issue or merge request. After reading surrounding context, either Claude or OpenAI's Codex CLI will decide whether code, review feedback, or clarification is required and will respond inside GitLab with either a ready-to-merge change or an in-line comment. This brings GitLab to feature parity with GitHub's AI-assisted development capabilities across multiple AI providers.

Problem Statement

GitLab customers observe competitors on GitHub accelerating delivery with AI assistance while they rely on manual effort for identical tasks. The absence of native GitLab experiences for leading AI coding tools creates a feature gap that needs to be closed to maintain platform competitiveness. Both Claude Code and OpenAI Codex CLI have become industry standards for AI-assisted development, and GitLab must support both to meet diverse team preferences.

Target Outcomes

  • Developers reach the "merged" state faster because Claude or Codex drafts or fixes changes directly inside the existing merge-request flow
  • Reviewers focus on design rather than syntax because AI assistants apply project conventions defined in repository-level CLAUDE.md or CODEX.md guide files
  • Teams demonstrate the same AI-assisted productivity available on competing platforms
  • Organizations can choose their preferred AI assistant based on model capabilities, cost, or existing API investments

User Narrative

A developer opens an issue describing a bug and closes the description with @claude @Claude please fix this or @codex please fix this. The chosen AI assistant inspects the repository, prepares a patch that follows project rules, and opens a new merge request linked back to the issue. During code review, a teammate requests changes; instead of editing the patch themselves, they @claude or @codex in the thread, which refines the code and force-pushes an updated commit. All communication, history, and permission checks remain entirely inside GitLab.

Functional Boundaries

Both AI assistants must trigger on their respective mentions in issues, comments, or merge-request threads. Specifically, the integration must monitor:

  • Issue notes (via Issues Notes API)
  • Merge request notes (via MR Notes API)
  • Merge request discussions (via MR Discussions API)

Each assistant must automatically gather only the context required to fulfill the request and surface its output either as an updated branch or a threaded response. All project-specific rules, including style, testing, and security policies, come exclusively from CLAUDE.md for Claude or CODEX.md for Codex CLI. Authentication flows through masked CI/CD variables (CLAUDE_API_KEY or OPENAI_API_KEY), which allows SaaS and self-managed instances to opt in without exposing secrets.

User Experience Expectations

Although each @claude or @codex mention starts a short-lived CI/CD pipeline, the interaction should feel conversational. Each assistant will post an immediate "processing ⏳" comment so users know the request is acknowledged, then replace that placeholder with the final patch or review note once the job completes. Typical tasks should finish within the few-minute window developers already associate with GitLab jobs. The integration honors existing repository permissions and never leaks credentials or code across project boundaries.

Implementation Requirements

Enabling either feature must remain simple: teams insert a single template block in .gitlab-ci.yml and add one masked variable.

For Claude:

include:
  - project: 'gitlab-org/claude-integration'
    ref: main
    file: '/templates/claude.yml'

variables:
  CLAUDE_API_KEY: $CLAUDE_API_KEY  # Masked CI/CD variable

For Codex CLI:

include:
  - project: 'gitlab-org/codex-integration'
    ref: main
    file: '/templates/codex.yml'

variables:
  OPENAI_API_KEY: $OPENAI_API_KEY  # Masked CI/CD variable
  CODEX_MODEL: "o4-mini"  # Optional: defaults to o4-mini

Technical Dependencies

Based on PoC work, the integration will likely require:

  • Custom Docker images containing integration tooling for each AI assistant:
    • Claude integration image: Claude Code binary, GitLab API clients, necessary dependencies
    • Codex integration image: Node.js 22+, @openai/codex package, GitLab API clients
  • Images must be maintained in GitLab Container Registry and regularly updated
  • Consider offering both alpine and ubuntu base variants for compatibility
  • Clear documentation on any limitations of the containerized environment
  • Codex CLI requires sandboxed execution with network restrictions (only OpenAI API access)

The custom image requirement is acceptable as long as:

  • It's automatically pulled/updated (users don't manage it)
  • It's officially maintained by GitLab
  • It supports common CI/CD patterns (caching, artifacts, etc.)
  • Security constraints are properly configured (especially for Codex's sandbox requirements)

Adoption Path

  • Quick-start templates in official GitLab project templates for both integrations
  • Public sample repositories demonstrating common use cases for each AI assistant
  • Documentation integrated into GitLab's existing CI/CD guides
  • Clear comparison guide helping teams choose between Claude and Codex based on their needs

Implementation Success Criteria

The implementation is complete when:

  • Feature parity achieved: All capabilities from GitHub's claude-code-action and OpenAI's Codex CLI work in GitLab
  • Integration is reliable: 90%+ success rate for standard code generation and review tasks across both assistants
  • Setup is simple: Less than 7 minutes from decision to first @claude or @codex mention (including any image pulls)
  • Performance acceptable: Response times comparable to other GitLab CI/CD jobs for both assistants
  • Infrastructure stable: Custom Docker images build automatically, update seamlessly, and support major GitLab runner types
  • Multi-model support: Teams can use both AI assistants in the same project without conflicts

Future Considerations

Once Claude, Codex, and GitLab's native agents all support advanced AI-assisted workflows, teams can choose or combine AI assistants based on their needs. The consistent interface (@assistant-name) will allow seamless transitions and comparisons between different AI providers. Teams may prefer Claude for complex reasoning tasks while using Codex for rapid prototyping with its multimodal capabilities, or leverage GitLab's native agents for proprietary code that cannot leave the infrastructure.

Implementation is being covered in https://gitlab.com/groups/gitlab-org/-/epics/18769

Edited by 🤖 GitLab Bot 🤖