162 lines
8.3 KiB
Markdown
162 lines
8.3 KiB
Markdown
# Agent CI
|
|
|
|
Agent CI is a private Gitea webhook host that turns issue and pull-request comments into resumable
|
|
OpenCode planning and implementation workflows. Docker Compose runs the webhook worker and a
|
|
private OpenCode server 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. |
|
|
|
|
The requester must have Gitea `write`, `admin`, or `owner` permission on the repository. Commands
|
|
are durably sequenced when their webhook arrives, then authorized and executed in receive order per
|
|
issue or pull request. Up to `AGENTCI_MAX_CONCURRENT_JOBS` unrelated targets execute concurrently;
|
|
the default is two. Each command gets one Gitea comment, which is reconciled asynchronously through
|
|
queued, running, and terminal states. Deleted comments are rediscovered by their hidden marker or
|
|
recreated.
|
|
|
|
## 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, Gitea URL, and provider-qualified
|
|
OpenCode models.
|
|
3. Create `secrets/gitea_token`, `secrets/webhook_secret`, and
|
|
`secrets/opencode_server_password`. Use high-entropy values for both secret/password files.
|
|
4. Build the image:
|
|
|
|
```sh
|
|
docker compose build
|
|
```
|
|
|
|
5. Authenticate the configured OpenCode providers before starting the persistent server:
|
|
|
|
```sh
|
|
docker compose run --rm opencode opencode auth login
|
|
docker compose run --rm opencode opencode auth list
|
|
```
|
|
|
|
6. Start the services:
|
|
|
|
```sh
|
|
docker compose up --no-build -d
|
|
```
|
|
|
|
7. In Gitea, create a JSON webhook targeting `http://agentci:8080/webhooks/gitea`. Set the same
|
|
webhook secret and subscribe to issue comments, PR timeline comments, and PR review comments.
|
|
|
|
OpenCode caches provider state. After adding or changing authentication on an already running
|
|
deployment, run the one-off `auth login` command above and then `docker compose restart opencode`.
|
|
|
|
`/health/live` reports process health. `/health/ready` returns 503 until the OpenCode server is
|
|
healthy and every configured model exists, supports tool calls, accepts its configured variant, and
|
|
has a connected provider. The worker leaves jobs queued while the runtime is unavailable.
|
|
|
|
## OpenCode
|
|
|
|
Models use OpenCode's `provider/model` format. Planning, implementation, and research can use
|
|
different providers. Optional `AGENTCI_PLAN_VARIANT` and `AGENTCI_IMPLEMENT_VARIANT` values are
|
|
passed directly to OpenCode for providers that support variants. `AGENTCI_RESEARCH_VARIANT`
|
|
configures the research subagent and defaults to `high`. `AGENTCI_EXPLORE_MODEL` and
|
|
`AGENTCI_EXPLORE_VARIANT` configure OpenCode's explore agent and default to
|
|
`openai/gpt-5.6-luna` with `low`.
|
|
|
|
`AGENTCI_OPENCODE_VERSION` controls the npm version or range installed into the image and defaults
|
|
to `^1`. The build verifies that the resolved version is still OpenCode 1.x and prints it. Docker
|
|
may reuse the cached installation layer until the configured version or build inputs change.
|
|
Runtime auto-update is disabled so an image cannot cross into OpenCode 2.x after it is built.
|
|
|
|
The trusted configuration is `opencode/opencode.json`. OpenCode's default global and built-in-agent
|
|
permission policies remain in effect; Agent CI does not replace them with an allow-all policy.
|
|
Repository-local OpenCode config and external plugins are disabled so a clone cannot replace the
|
|
service policy. OpenCode's default plugins remain enabled for provider authentication. Its scanned
|
|
home and global configuration paths are root-owned and read-only, and external skill discovery is
|
|
disabled, so an agent cannot persist instructions for later repositories. CodeGraph, Context7, and
|
|
`gh_grep` are configured as MCP servers. Set `AGENTCI_CONTEXT7_API_KEY` to raise Context7 rate
|
|
limits.
|
|
|
|
The `research` subagent can only use Exa web search, Context7, and the `gh_grep` public-code search
|
|
MCP. All filesystem, shell, editing, task, and other tools are denied for that agent. Exa is enabled
|
|
with `OPENCODE_ENABLE_EXA=1`. Agent CI initializes or refreshes CodeGraph before every parent turn
|
|
and locally excludes `.codegraph/` from Git.
|
|
|
|
### Security boundary
|
|
|
|
OpenCode does not provide an OS sandbox. Its default permission system controls agent tools and
|
|
approval requests, while Docker limits what the non-root process can reach. Any shell command that
|
|
OpenCode permits still has the Unix-level access of that container user, so environment filtering
|
|
is only accidental-exposure hygiene and cannot protect readable files from an allowed shell command.
|
|
|
|
Docker remains the OS boundary. The services run as non-root without added capabilities,
|
|
privileged mode, an unconfined seccomp/AppArmor profile, or a nested `bubblewrap` sandbox. The only
|
|
host bind mount is the read-only installer directory; there are no
|
|
writable host filesystem mounts. The OpenCode HTTP server is not published to the host, is password
|
|
protected, and is reachable by Agent CI over an internal Compose network.
|
|
|
|
## 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 can be replaced or
|
|
removed. Configure them 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 a file in `install-scripts/`, mounted read-only at
|
|
`/etc/agentci/install-scripts`. Names cannot contain paths and duplicates are rejected. Installers
|
|
run after each implementation clone or branch sync and fail the job on an unknown script, timeout,
|
|
or non-zero exit. They receive no Agent CI or Gitea secret values in their environment, but remain
|
|
trusted operator code. Tools persist under `/var/lib/agentci/dev-tools`, and OpenCode can read or
|
|
modify them through shell commands permitted by its active agent policy. See
|
|
`install-scripts/README.md` for the script contract.
|
|
|
|
Agent CI continues to create branches, validate diffs, commit, and push after OpenCode returns. This
|
|
keeps workflow behavior deterministic, but an OpenCode agent with shell permission can still run
|
|
Git commands itself.
|
|
|
|
## State and recovery
|
|
|
|
The `agentci_data` volume contains SQLite, workflow clones, and installed development runtimes.
|
|
The `opencode_home` volume contains provider authentication, OpenCode's database, and resumable
|
|
sessions. Tea's Gitea token configuration is regenerated in an ephemeral tmpfs and is not copied to
|
|
`opencode_home`. Back up both persistent volumes together.
|
|
|
|
SQLite stores the current job state, an idempotent event inbox, and durable listener tasks. State
|
|
transitions and workflow creation/linking commit atomically; timestamps are storage metadata rather
|
|
than reducer state. Control effects retry with bounded backoff. A delayed authorization blocks later
|
|
workflow execution for the same issue or pull request, but not other targets or later control work.
|
|
Development environment installers remain serialized because they share the persistent tools
|
|
directory.
|
|
|
|
The OpenCode migration tags existing workflows as Codex-owned and preserves their session IDs for
|
|
rollback, but OpenCode refuses to resume them. Follow-up commands against those workflows ask for a
|
|
new plan or implementation. Queued jobs survive restart. A restart before `JobStarted` returns the
|
|
task to the queue; after `JobStarted`, the job is failed, its sessions are aborted, and execution is
|
|
never replayed because a partial model turn may already have changed files. Git pushes are never
|
|
forced.
|
|
|
|
## Development
|
|
|
|
Install and validate with:
|
|
|
|
```sh
|
|
uv sync
|
|
uv run ruff check .
|
|
uv run pyright
|
|
uv run pytest
|
|
docker compose config
|
|
docker compose build
|
|
```
|
|
|
|
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.
|