gitea-codex/README.md

Gitea Codex Review Bot

Webhook-driven PR review bot for Gitea.

Features

• Handles issue_comment and pull_request_comment events.
• Verifies X-Gitea-Signature HMAC (sha256).
• Triggers on @codex review, @codex rerun, @codex explain, @codex fix, @codex ignore.
• Ignores bot-authored comments.
• Enforces strict repository allowlist (ALLOWED_REPOS).
• Deduplicates webhook deliveries/comments in DB.
• Enforces PR cooldown for review requests.
• Uses MariaDB + SQLAlchemy + Alembic.
• Runs review jobs through ephemeral runner containers (with local fallback if Docker runtime is unavailable).
• Posts/updates one persistent PR summary comment.
• Supports repository config via .codex-review.yml.

Endpoints

• POST /webhook/gitea
• GET /healthz

Webhook Setup Model

This bot is designed for self-hosted deployment:

1. You host this service yourself.
2. A Gitea admin points webhook events to your hosted endpoint:
   • https://your-bot-domain/webhook/gitea
3. Gitea sends issue_comment and pull_request_comment events to that endpoint.

Webhook configuration is manual by design.

Detailed setup instructions for both global and repository-only webhooks:

• docs/webhook-setup.md

Environment

Use .env.example as template.

Required:

• GITEA_BASE_URL
• GITEA_TOKEN
• GITEA_BOT_USERNAME
• GITEA_WEBHOOK_SECRET
• ALLOWED_REPOS
• DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD

Optional:

• OPENAI_API_KEY (required when CODEX_AUTH_MODE=api_key, optional when CODEX_AUTH_MODE=chatgpt)
• OPENAI_PROJECT_ID
• OPENAI_ORG_ID
• CODEX_AUTH_MODE (api_key default, or chatgpt)
• CODEX_AUTH_JSON_PATH (custom host path to auth.json; defaults to ~/.codex/auth.json in chatgpt mode)
• DATABASE_URL (overrides composed DB URL)

Local Run

python -m pip install -e .[dev]
alembic upgrade head
uvicorn gitea_codex_bot.main:app --host 0.0.0.0 --port 8000

Docker Compose

# Local dev image build
docker compose -f docker-compose.dev.yml up --build

# Published image
docker compose up

CI

The workflow in .gitea/workflows/ci.yml:

1. starts MariaDB service,
2. runs Alembic migrations + tests,
3. builds and pushes image tags to gitea.reversed.dev/space/gitea-codex on push.

Expected secrets for publish job:

• REGISTRY_USERNAME
• REGISTRY_PASSWORD