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 ..., @<GITEA_BOT_USERNAME> ..., plus optional custom aliases from GITEA_BOT_MENTIONS.
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:

You host this service yourself.
A Gitea admin points webhook events to your hosted endpoint:
- https://your-bot-domain/webhook/gitea
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
GITEA_BOT_MENTIONS (comma-separated extra mention aliases, e.g. @review-buddy,helper-bot)
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:

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

Expected secrets for publish job:

REGISTRY_USERNAME
REGISTRY_PASSWORD

AI Note

This project is a super big experiment i made because i wanted to have codex reviews in gitea. I hate using Github and i will never willingly without good reasons use their copilot bs. This project was made WITH codex and is meant to be used WITH codex as a review agent. If you are as rich as Peter Steinberg and get a free OpenAI API Key, feel free to use it for this bot.

Contributing

Contributions are welcome! Please open issues or submit pull requests for bug fixes, improvements, or new features.

3.0 KiB Raw Blame History