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

Anyone who can comment on an issue or pull request 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.

Every planning and implementation session can delegate external research to a
read-only `research` subagent. It defaults to `gpt-5.6-luna` with high reasoning
and has public network access, live web search, Context7 documentation lookup,
and `gh_grep` public GitHub code search. Configure its model and effort with
`AGENTCI_RESEARCH_MODEL` and `AGENTCI_RESEARCH_REASONING`. Context7 works
without authentication at lower rate limits; set the optional
`AGENTCI_CONTEXT7_API_KEY` for authenticated usage. The key is passed only to
Codex's Context7 MCP transport and is excluded from agent shell environments.

Planning, implementation, and all review sessions also receive the local
CodeGraph MCP server for repository structure, symbol relationships, and change
impact. Agent CI initializes or refreshes the index before every Codex turn and
locally excludes `.codegraph/` from Git. The research subagent intentionally
does not receive CodeGraph.

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. Codex's interactive Git trust check is
skipped because every turn runs non-interactively against a service-owned clone;
the configured filesystem and network permissions still apply. Git credentials
exist only in the service-owned clone/push subprocess and are not inherited by
Codex turns. The image and Compose capability/security settings let the non-root
service create Codex's nested `bwrap` sandbox. They follow Codex's secure
devcontainer pattern instead of making the service container privileged. Do not
remove Codex's configured filesystem and network restrictions.

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