gitea-codex/AGENTS.md

AGENTS.md

Guidance for autonomous/code-assist agents working in this repository.

Mission

Build and maintain a webhook-driven Gitea PR review bot that:

1. verifies webhook authenticity,
2. parses @codex commands,
3. queues and executes review jobs,
4. posts/updates PR comments with structured findings.

Primary implementation lives under src/gitea_codex_bot.

Tech Stack

• Python >=3.11
• FastAPI + Uvicorn
• SQLAlchemy + Alembic
• MariaDB (default), SQLite possible via DATABASE_URL
• Pytest for tests
• Docker-based review runner with host fallback

Repository Map

• src/gitea_codex_bot/main.py
  • FastAPI app, /healthz, /webhook/gitea, lifespan worker boot.
• src/gitea_codex_bot/config.py
  • Environment-backed settings and DB URL composition.
• src/gitea_codex_bot/db.py
  • Engine/session factory and dependency session provider.
• src/gitea_codex_bot/models.py
  • ORM models: WebhookEvent, ReviewJob, ReviewRun, BotComment.
• src/gitea_codex_bot/services/commands.py
  • @codex command parsing.
• src/gitea_codex_bot/services/jobs.py
  • Event dedupe, queue transitions, cooldown logic.
• src/gitea_codex_bot/services/security.py
  • HMAC signature verification and payload digest.
• src/gitea_codex_bot/services/gitea.py
  • Gitea API client wrapper.
• src/gitea_codex_bot/services/reviewer.py
  • PR checkout/diff collection/prompt build/OpenAI call/fallback/fix helpers.
• src/gitea_codex_bot/services/review_format.py
  • Outbound comment formatting.
• src/gitea_codex_bot/services/comments.py
  • Persistent summary comment id tracking.
• src/gitea_codex_bot/workers/dispatcher.py
  • Job polling and orchestration.
• src/gitea_codex_bot/workers/container_runner.py
  • Docker review execution + fallback.
• alembic/ + alembic.ini
  • Database migrations.
• tests/
  • Unit/integration-ish tests across config/security/jobs/webhook/migrations.
• .gitea/workflows/ci.yml
  • CI test + publish workflow.

Runtime Flow

1. Gitea sends webhook to POST /webhook/gitea.
2. Signature is validated (X-Gitea-Signature, sha256 HMAC).
3. Non-supported events are ignored.
4. PR context and command are extracted.
5. Repo allowlist and dedupe checks run.
6. Job is enqueued (review_jobs).
7. Background worker claims queued jobs.
8. For review/rerun:
   • fetch PR context,
   • run review in ephemeral container if possible,
   • fallback to host execution on failure,
   • post or edit persistent PR summary comment.
9. Job/run status transitions are persisted.

Supported Commands

• @codex review [security|performance|tests] [--full]
• @codex rerun
• @codex explain
• @codex fix [--branch ...] (gated by ENABLE_FIX_COMMANDS)
• @codex ignore

Local Development

Install and run:

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

Run tests:

pytest

Docker compose:

Locally only run this, is pre setup to use the dev compose file.

docker compose up --build -f docker-compose.dev.yml

Environment Contract

Required:

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

Common optional:

• DATABASE_URL (overrides DB parts)
• OPENAI_API_KEY (required when CODEX_AUTH_MODE=api_key)
• OPENAI_PROJECT_ID, OPENAI_ORG_ID
• OPENAI_REVIEW_MODEL
• OPENAI_REASONING_EFFORT
• CODEX_AUTH_MODE (api_key default, chatgpt supported)
• CODEX_AUTH_JSON_PATH (custom path to auth.json for chatgpt mode)
• WORKDIR, MAX_DIFF_BYTES, MAX_REVIEW_MINUTES, CONCURRENCY
• REVIEW_RUNNER_IMAGE
• ENABLE_FIX_COMMANDS
• ALLOW_UNTRUSTED_FORKS

Database and Migrations

• SQLAlchemy models are authoritative for runtime behavior.
• Alembic migrations in alembic/versions must track schema changes.
• If model schema changes, add a migration and keep migration tests passing.
• CI runs alembic upgrade head before pytest.

Testing Expectations

Before opening/merging changes:

1. run pytest,
2. if DB/model changes were made, ensure migration test still passes,
3. for webhook/queue logic, add or update focused tests in tests/.

Current tests rely on tests/conftest.py to inject default env and DB URL behavior.

Change Guardrails

• Preserve webhook security checks and allowlist semantics.
• Preserve dedupe constraints (delivery_id, repo+comment_id, repo+trigger_comment_id).
• Keep bot self-comment ignore behavior.
• Keep persistent comment update behavior (avoid comment spam regressions).
• Be explicit when changing runner isolation/fallback behavior; this is a security-sensitive area.
• Keep response payloads and command parsing backward compatible unless intentionally versioned.

Known Risks / Active Gaps

See TODO.md for priority backlog, especially:

• stronger isolated runner flow,
• stricter host fallback controls,
• end-to-end integration coverage.

Treat these as high-sensitivity areas when modifying worker/runner paths.

Recommended Workflow for Agents

1. Read touched service + corresponding tests first.
2. Make minimal cohesive changes.
3. Add/update tests with behavior changes.
4. Run pytest.
5. Summarize impact, risks, and follow-ups in PR/commit notes.

Commiting After Completion

If you are confident that your changes are ready to be committed, please follow the commit message format below:

[type]. Short description (max 50 chars) Push after commiting. Ask the user once if you have permission to commit and from then on commit without asking.