gitea-codex/README.md

Gitea Codex Review Bot

A self-hosted, webhook-driven pull-request review bot for Gitea, rebuilt in Go. It validates signed Gitea comment webhooks, queues durable review jobs, runs Codex in an isolated container at the exact PR head SHA, and posts structured feedback back to the pull request.

Features

• HMAC-SHA256 verification of X-Gitea-Signature over the raw webhook body.
• issue_comment and pull_request_comment support.
• @codex, bot-username, and configured mention aliases.
• Bot-loop prevention and exact ALLOWED_REPOS enforcement.
• Delivery/comment deduplication and PR review cooldowns.
• Durable FIFO jobs with retry and stale-running-job recovery.
• MariaDB-compatible persistence with SQLite support for local tests.
• .codex-review.yml at the exact PR head SHA.
• Fork review policy, disabled-repository acknowledgements, and non-review commands.
• Strict structured review result validation and bounded Markdown comments.
• Isolated Docker runner with detached exact-SHA checkout verification.
• Health and operational endpoints with bounded error output.

The runner executes untrusted repository content. Secure the Docker API/socket, use least-privilege tokens, pin the runner image, restrict egress, and review the threat model before production use.

Routes

• GET / — embedded service landing page.
• GET /healthz — liveness response: {"status":"ok"}.
• GET /healthz/latest-job — bounded latest-job metadata.
• GET /healthz/latest-failure — bounded latest-failure metadata.
• POST /webhook/gitea — signed Gitea webhook receiver.

Commands

@codex review
@codex review security
@codex review performance --full
@codex review tests
@codex rerun
@codex explain
@codex ignore
@codex help

Commands must begin the comment. @codex fix is intentionally unsupported. Unknown prefixed commands receive an explanatory comment; ordinary comments without a command are ignored.

Configuration

Copy .env.example to .env. Required values:

• GITEA_BASE_URL
• GITEA_TOKEN
• GITEA_BOT_USERNAME
• GITEA_WEBHOOK_SECRET
• ALLOWED_REPOS
• DATABASE_URL or DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
• OPENAI_API_KEY when CODEX_AUTH_MODE=api_key

Important optional values include OPENAI_REVIEW_MODEL, CODEX_AUTH_MODE, CODEX_AUTH_JSON_PATH, COOLDOWN_SECONDS, MAX_REVIEW_MINUTES, CONCURRENCY, REVIEW_RUNNER_IMAGE, ALLOW_UNTRUSTED_FORKS, and WEBHOOK_MAX_BYTES.

For local development, use SQLite:

DATABASE_URL=sqlite://./gitea-codex.db

For production, use MariaDB and a scoped Gitea token. The Go service applies schema migrations on startup.

Local development

Requirements: Go 1.25+, Docker for real review execution, and Gitea credentials for integration use.

go mod download
go test ./...
go vet ./...
go build -trimpath -o gitea-codex ./cmd/gitea-codex

# With environment configured:
./gitea-codex

The default listener is :8000; set PORT to change it. The unit/integration tests use a temporary SQLite database and fake Gitea HTTP server, so they do not require a live Gitea instance or Docker.

Docker Compose

cp .env.example .env
# Edit .env, then:
docker compose -f docker-compose.dev.yml up --build

The bot container needs access to the host Docker API to launch isolated review containers. Mounting /var/run/docker.sock is a privileged deployment decision; use a dedicated runner service or hardened Docker host where possible. docker-compose.yml consumes the published image, while docker-compose.dev.yml builds locally. ChatGPT auth mode should use a private Compose override to mount auth.json; the checked-in Compose files do not mount it in API-key mode.

Repository configuration

A target repository may provide .codex-review.yml:

enabled: true
review:
  default_mode: full
  max_diff_bytes: 200000
  include_tests: false
  focus:
    - correctness
    - security
    - maintainability
ignore:
  - generated/

The file is read from the PR head and is treated as untrusted data. It cannot choose commands, credentials, images, host paths, container privileges, or network policy. Tests are disabled by default; use tests mode only when the deployment explicitly accepts execution of repository code in the runner.

Webhooks and deployment

Webhook provisioning is manual in Gitea. See docs/webhook-setup.md for global and repository-only configuration. CI runs Go formatting, race-enabled tests, vet, and a static build before publishing an image.

Design notes

This project exists to provide Codex-based review workflows for self-hosted Gitea installations without requiring GitHub. The implementation is intentionally provider- and runner-bound at the outer edge, while the domain, queue, storage, and HTTP layers remain independently testable.