# 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.