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

```text
@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:

```dotenv
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.

```bash
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

```bash
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.

## Repository configuration

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

```yaml
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; `tests` mode or `include_tests: true` explicitly permits the runner to execute project tests.

## Webhooks and deployment

Webhook provisioning is manual in Gitea. See [docs/webhook-setup.md](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.