Space-Banane
f19b271642
Rebuild the Gitea Codex review bot from the product contract with a Go HTTP service, durable SQL queue, typed Gitea client, isolated runner, and deployment updates. Co-Authored-By: Claude <noreply@anthropic.com>
85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|