135 lines
6.0 KiB
Markdown
135 lines
6.0 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. |
|
|
|
|
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.
|
|
|
|
### 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`:
|
|
|
|
```env
|
|
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.
|
|
|
|
## 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:
|
|
|
|
```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.
|