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.

Environment

Use .env.example as template.

Required:

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

Optional:

• OPENAI_PROJECT_ID
• OPENAI_ORG_ID
• 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

docker compose up --build

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