87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# 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.
|
|
|