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

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.

Development environments

AGENTCI_INSTALL_SCRIPTS is a comma-delimited ordered list of development environment installers. The supplied python and dotnet scripts install only their runtimes; they are ordinary scripts that can be replaced or removed. Implementation agents remain responsible for restoring project dependencies and selecting build/test commands. Configure the supplied scripts with AGENTCI_PYTHON_VERSION and AGENTCI_DOTNET_CHANNEL:

AGENTCI_INSTALL_SCRIPTS=python,dotnet,company-tools
AGENTCI_PYTHON_VERSION=3.13
AGENTCI_DOTNET_CHANNEL=10.0

Every name resolves to an executable file in install-scripts/, mounted read-only at /etc/agentci/install-scripts. Names cannot contain paths and duplicates are rejected. See install-scripts/README.md for the script contract.

Installers run in order after each implementation clone or branch sync and fail the job on an unknown script, timeout, or non-zero exit. They receive no AgentCI or Gitea secret values in their environment, but remain trusted operator code running as the service user. Tools persist under /var/lib/agentci/dev-tools; its bin directory is added to implementation agents' PATH with read-only sandbox access. The agents can use those tools for builds and validation, but Agent CI does not impose host-side build commands.

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. In particular, systempaths=unconfined removes Docker's outer masked /proc subpaths so the nested user/PID namespace can mount its own procfs. Runtimes such as CoreCLR require /proc/self/maps; Codex still controls visibility through the fresh procfs and its filesystem policy.

State and recovery

The agentci_data volume contains SQLite, persistent workflow clones, and installed development runtimes. 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.

6.3 KiB Raw Blame History