gitea-codex/AGENTS.md

AGENTS.md

Guidance for autonomous/code-assist agents working in this repository.

Mission

Maintain a Go service that:

1. verifies Gitea webhook authenticity,
2. parses @codex commands,
3. queues and executes durable review jobs,
4. checks out the exact pull-request head SHA in an isolated runner,
5. posts structured findings back to Gitea.

Tech stack

• Go 1.25+
• net/http
• database/sql
• MariaDB in production; SQLite for local tests
• embedded Go migrations
• Docker-based review runner
• standard Go tests, race detector, vet, and formatting checks

Repository map

• cmd/gitea-codex/main.go — process startup, signals, migrations, HTTP server, worker.
• internal/config — environment loading and startup validation.
• internal/domain — typed commands, job/run states, review results, and policies.
• internal/commands — mention aliases and safe command lexer.
• internal/webhook — raw-body HMAC and typed event extraction.
• internal/httpapi — routes, webhook acknowledgements, and health endpoints.
• internal/store and internal/store/sqlstore — storage contracts, migrations, transactions, and queue claims.
• internal/gitea — typed Gitea REST client.
• internal/review — repository config, prompts, result validation, and comment formatting.
• internal/runner — Docker/Codex execution and cleanup.
• internal/worker — queue orchestration, retries, stale recovery, and non-review commands.
• migrations — logical compatibility baseline and migration notes.
• tests under internal/* — unit and fake-service integration tests.

Runtime flow

1. Gitea sends a signed webhook to POST /webhook/gitea.
2. The handler verifies the raw body, filters event/repository/bot policy, parses the command, deduplicates, and persists a job.
3. The worker claims the oldest queued job and records a run attempt.
4. Review/rerun jobs fetch PR metadata, enforce fork policy, read .codex-review.yml at the exact head SHA, and invoke the isolated runner.
5. The runner checks out the exact head SHA, verifies git rev-parse HEAD, invokes Codex, and returns strictly validated JSON.
6. The worker posts a new result/failure/acknowledgement comment and finalizes durable state.

Compatibility guardrails

• Preserve HMAC verification, allowlisting, bot self-comment filtering, and event/job dedupe.
• Preserve response reasons and command behavior unless intentionally versioned.
• Keep cooldown for review; rerun bypasses cooldown.
• Allow two requeues after an initial failed attempt, then fail terminally.
• Recover running jobs after the five-minute lease timeout.
• Skip fork reviews by default.
• Do not add host-side Codex fallback.
• Keep posting new review comments while updating the bot_comments latest mapping; do not silently change to edit-in-place behavior.
• Never mark infrastructure failure as a successful review.
• Treat PR content, comments, .codex-review.yml, and model output as untrusted data.

Security-sensitive areas

• Do not log Gitea/OpenAI tokens, auth JSON, Docker arguments containing secrets, raw prompts, or unbounded provider output.
• Do not pass Docker socket access into review containers.
• Pin runner images and Codex versions for production.
• Enforce body/output limits, context cancellation, container cleanup, and exact SHA verification.
• Keep repository configuration from controlling credentials, images, host paths, commands, privileges, or network policy.
• Review changes to internal/runner, internal/webhook, internal/store/sqlstore, and internal/gitea carefully.

Development checks

Before proposing a change:

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go build -trimpath ./cmd/gitea-codex

Changes affecting migrations, queue claims, or HTTP contracts require focused tests. MariaDB locking behavior must be verified separately from SQLite; SQLite tests do not prove FOR UPDATE SKIP LOCKED correctness.