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. Each accepted 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, Gitea URL, and provider-qualified OpenCode models.
Create secrets/gitea_token, secrets/webhook_secret, and secrets/opencode_server_password. Use high-entropy values for both secret/password files.
Build the image:
```
./scripts/build.sh
```

Authenticate the configured OpenCode providers before starting the persistent server:

docker compose run --rm opencode opencode auth login
docker compose run --rm opencode opencode auth list

Start the services:
```
docker compose up --no-build -d
```
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.

scripts/build.sh supplies a unique required cache key on every invocation. The image then runs npm install -g 'opencode-ai@^1', verifies the installed major version, and prints it. Compose also requests a no-cache build. A direct build without OPENCODE_REFRESH fails rather than silently reusing an old OpenCode installation layer. This is intentionally fresh rather than reproducible. 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. It grants permission: "allow" globally and to every built-in or custom agent that Agent CI can invoke. Repository-local OpenCode config and plugins are disabled so a clone cannot replace the service policy. OpenCode's 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 has the same unrestricted permissions as every other agent. Its prompt asks it to focus on external evidence, but this is guidance rather than an isolation boundary. Agent CI initializes or refreshes CodeGraph before every turn and locally excludes .codegraph/ from Git.

Security boundary

OpenCode does not provide an OS sandbox. It can execute shell commands, edit Git metadata and environment files, access external directories, use loopback and network services, bind ports, and invoke subagents without approval. It can access every shared workspace, development tool, runtime credential, and mounted file readable by the non-root container user. Environment filtering is only accidental-exposure hygiene and cannot protect readable files from shell commands.

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:

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 its unrestricted shell. 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 unrestricted OpenCode is not prevented from running 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.

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. An in-progress job is aborted in OpenCode and marked failed instead of being replayed because a partial model turn may already have changed files. Git pushes are never forced.

Development

Install and validate with:

uv sync
uv run ruff check .
uv run pyright
uv run pytest
docker compose config
./scripts/build.sh

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.