codexer

use OpenAI codex on GitLab PRs

Development

Prerequisites

• Python 3.11
• Docker Engine available on the same host that runs the webhook service

Install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the webhook server with hot reload:

uvicorn src.webhooks.app:app --host 0.0.0.0 --port 8000 --reload

Set CODX_GITLAB_WEBHOOK_SECRET to the token you configured in GitLab so webhook requests are validated. Provide a GitLab access token by exporting CODX_GITLAB_USER_TOKEN (preferred) or CODX_GITLAB_GROUP_TOKEN so the service can fetch issue details and push branches. A legacy CODX_GITLAB_PROJECT_TOKEN or CODX_GITLAB_TOKEN value is still supported as a fallback. Instance-wide system hooks are enabled by default; set CODX_GITLAB_SYSTEM_HOOK_ENABLED=false if you want to stick with per-project or per-group webhooks (required on GitLab SaaS where system hooks are unavailable).

GitLab TL;DR (Instance-wide)

• Requires GitLab administrator access on a self-managed instance.
• Create a user (preferred) or group access token with scopes api, read_repository, and write_repository, then export it as CODX_GITLAB_USER_TOKEN or CODX_GITLAB_GROUP_TOKEN.
• Navigate to Admin → System Hooks and add a hook pointing to https://<your-host>:8000/webhooks/gitlab/issues (use http:// locally).
• Check Issues events (and Confidential issues events if you need them) and supply the same secret as CODX_GITLAB_WEBHOOK_SECRET.
• Save the hook. The service will retrieve project details on-demand for each issue event.

Legacy Project/Group Setup

1. Access token

   • Prefer creating a user token via User → Edit profile → Access Tokens and export it as CODX_GITLAB_USER_TOKEN.
   • If you manage repositories under a shared namespace, create a group access token under Group → Settings → Access Tokens and export it as CODX_GITLAB_GROUP_TOKEN.
   • As a fallback you can create a project token under Project → Settings → Access Tokens (or Settings → Repository → Deploy Tokens) and export it as CODX_GITLAB_PROJECT_TOKEN or legacy CODX_GITLAB_TOKEN.

2. Webhook

   • For project-level hooks: go to Project → Settings → Webhooks.
   • For group-level hooks: go to Group → Settings → Webhooks.
   • URL: https://<your-host>:8000/webhooks/gitlab/issues (http:// for local testing).
   • Secret token: reuse CODX_GITLAB_WEBHOOK_SECRET.
   • Trigger: enable Issues events (and Confidential issues events if needed).
   • Save and use the “Test” button to confirm the 202 response.

3. Self-managed GitLab instances

   • Export CODX_GITLAB_BASE_URL=https://gitlab.goober.cloud (replace with your domain).
   • Ensure the access token you created is valid on that instance and that the webhook endpoint is reachable.

Agent Container Image

Build the base agent image (installs the Codex CLI via npm):

docker build -t codex-agent -f docker/agent/Dockerfile .

At runtime the container entrypoint inspects AGENTS.md and installs any extra toolchains (Rust, Go, Java, .NET) that the project requires. Override the Codex package with --build-arg CODEX_NPM_PACKAGE=<your-cli> if the default @openai/codex name differs. The image also ships with /usr/local/bin/run_codex_agent.sh, the default Codex workflow launcher.

The webhook service launches containers via the following environment variables:

• CODX_AGENT_IMAGE (default codex-agent:latest)
• CODX_AGENT_WORKSPACE_ROOT (default /tmp/codex-agent)
• CODX_AGENT_COMMAND (default /usr/local/bin/run_codex_agent.sh)
• CODX_AGENT_COMMAND_SHELL (set to false to bypass bash -lc)
• CODX_AGENT_CONTAINER_NETWORK (optional for Docker network joins)
• CODX_GITLAB_BASE_URL (default https://gitlab.com)
• CODX_OPENAI_API_KEY (forwarded to the container as OPENAI_API_KEY)

Make sure docker is available to the FastAPI process and that your configured GitLab token (CODX_GITLAB_USER_TOKEN, CODX_GITLAB_GROUP_TOKEN, or the fallback project token) has clone permissions for private repositories. A per-run workspace is created under CODX_AGENT_WORKSPACE_ROOT and mounted into the container at /workspace (repo) and /agent-run (metadata/context).

The dispatcher sets OPENAI_API_KEY, CODEX_RUN_DIR, and CODEX_ISSUE_CONTEXT before running /usr/local/bin/run_codex_agent.sh inside the container. That script loads /agent-run/context/issue.json, prints basic diagnostics, and then invokes codex exec handle-issue --no-tty (falling back to codex handle-issue when the exec command is unavailable). Override CODX_AGENT_COMMAND if you need a different entrypoint.