initial impl

2026-07-19 12:21:26 +02:00
commit e9b895366d
64 changed files with 4113 additions and 0 deletions
@@ -0,0 +1,86 @@
+# Agent CI
+
+Agent CI is a private Gitea webhook host that turns issue and pull-request
+comments into resumable Codex planning and implementation workflows. It runs as
+one persistent Docker Compose service on the same Docker network as Gitea.
+
+## Commands
+
+| Location | Command | Behavior |
+| --- | --- | --- |
+| Issue | `/agent plan [message]` | Create and independently review a new canonical plan. |
+| Issue | `/agent discuss <message>` | Resume the newest planner and post its response. |
+| Issue | `/agent implement [message]` | Create, review, and open a PR. A prior plan is optional. |
+| Issue | `/agent iterate [message]` | Revise and review the plan once, unless an agent PR is open or merged. |
+| PR | `/agent iterate [message]` | Resume an agent implementation and its reviewer once. |
+| PR | `/agent fix [message]` | Start a fresh one-shot fix session and push one commit. |
+
+Only repository writers and administrators can enqueue commands. Each command
+gets separate queued and started comments. Final plans, PR results, failures,
+and remaining review findings are posted separately.
+
+## Deploy
+
+1. Create a Gitea bot user with repository read/write access and an API token.
+2. Copy `.env.example` to `.env` and set the external network and internal
+   Gitea URL.
+3. Create `secrets/gitea_token` containing the bot token and
+   `secrets/webhook_secret` containing a high-entropy webhook secret.
+4. Build and start the service:
+
+   ```sh
+   docker compose up --build -d
+   ```
+
+5. Authenticate Codex interactively in the persistent container:
+
+   ```sh
+   docker compose exec agentci codex login --device-auth
+   docker compose exec agentci codex login status
+   ```
+
+6. In Gitea, create a JSON webhook targeting
+   `http://agentci:8080/webhooks/gitea`. Set the same secret and subscribe to
+   issue comments, PR timeline comments, and PR review comments.
+
+`/health/live` reports process health. `/health/ready` returns 503 until Codex
+authentication is usable. The worker leaves jobs queued while authentication is
+missing.
+
+## Configuration
+
+Model, reasoning effort, review-pass counts, bot identity, branch prefix, and
+turn timeout use `AGENTCI_` environment variables. Defaults are shown in
+`.env.example`. Gitea credentials and webhook secrets are intentionally
+file-based Compose secrets.
+
+Planning/review commands can only read their workflow clone and have no shell
+network access. Implementation/fix commands can edit the clone but cannot
+modify `.git`; they can reach public internet destinations while private and
+loopback destinations remain blocked. Git credentials exist only in the
+service-owned clone/push subprocess and are not inherited by Codex turns.
+
+## State and recovery
+
+The `agentci_data` volume contains SQLite and persistent workflow clones.
+`codex_home` contains login state and resumable Codex sessions. Both are kept
+indefinitely and should be backed up together.
+
+Queued jobs survive restart. An in-progress job is marked failed after restart
+instead of being replayed, because replaying a partially completed model turn
+could duplicate changes. Git pushes are never forced.
+
+## Development
+
+Install and validate with:
+
+```sh
+uv sync
+uv run ruff check .
+uv run pyright
+uv run pytest
+```
+
+The tests fail if any tracked Python file exceeds 250 lines. Prompts and JSON
+schemas live outside Python so orchestration modules remain small and readable.
+