# Webhook setup

The Go service accepts signed Gitea webhooks at:

- `POST /webhook/gitea`

It processes only `issue_comment` and `pull_request_comment` events. The handler verifies the exact raw request body with HMAC-SHA256 using `GITEA_WEBHOOK_SECRET`, enforces `ALLOWED_REPOS`, ignores bot-authored comments, and queues recognized `@codex` commands.

## Configure Gitea

1. Deploy the service at a URL reachable by Gitea, for example `https://bot.example.com/webhook/gitea`.
2. Set the same random secret in Gitea and `GITEA_WEBHOOK_SECRET`.
3. Configure either an instance/global webhook or one repository webhook per target repository.
4. Use JSON content type and enable only Issue comment and Pull request comment events.
5. Add every allowed `owner/repository` to `ALLOWED_REPOS`.
6. Test the webhook from Gitea, then check `GET /healthz`.

`WEBHOOK_MODE=global` or `WEBHOOK_MODE=repo` is a deployment label; webhook provisioning remains an administrator responsibility.

## Environment

Required values are `GITEA_BASE_URL`, `GITEA_TOKEN`, `GITEA_BOT_USERNAME`, `GITEA_WEBHOOK_SECRET`, `ALLOWED_REPOS`, and either `DATABASE_URL` or the `DB_*` values. API-key Codex mode also requires `OPENAI_API_KEY`.

The recommended local development database is SQLite:

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

Production deployments should use MariaDB and a token with only the Gitea permissions needed to read pull requests/files and create comments. Keep the runner image pinned to a reviewed digest and treat review execution as untrusted code execution.

## Command examples

```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. Inline mentions in ordinary discussion text are intentionally ignored for compatibility. `@codex fix` is not supported.

## Security notes

- Invalid signatures return HTTP 401.
- Fork pull requests are skipped unless `ALLOW_UNTRUSTED_FORKS=true`.
- The bot launches review containers through the host Docker API; secure the Docker socket and runner host accordingly.
- The review container receives credentials required by the configured Codex/Gitea workflow. Use least-privilege credentials, restrict network access, and do not use unpinned images in production.
- Health detail endpoints expose bounded job metadata. Put them behind an internal network or reverse-proxy authentication if repository names and review errors are sensitive.