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

Create a Gitea bot user with repository read/write access and an API token.
Copy .env.example to .env and set the external network and internal Gitea URL.
Create secrets/gitea_token containing the bot token and secrets/webhook_secret containing a high-entropy webhook secret.
Build and start the service:
```
docker compose up --build -d
```

Authenticate Codex interactively in the persistent container:

docker compose exec agentci codex login --device-auth
docker compose exec agentci codex login status

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.

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:

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.