ci-agent-runner/README.md

# Olixero CI Agents

This directory contains the source for a dedicated, Dockerized Gitea runner that uses OpenCode and an OpenAI ChatGPT Pro subscription to plan and implement issues.

The runner handles two issue labels:

- `agent:plan`: create a plan, independently review it, revise it up to three times, and publish the accepted plan as one issue comment.
- `agent:implement`: read the accepted plan, implement it on a stable branch, independently review and revise the diff up to three times, then create or update a pull request.

The generated pull request is built and tested by the repository's existing PR workflow on a different runner. The credential-bearing agent runner never executes model-modified project code.

## Security Model

- The runner is dedicated to this workflow and registers only `agentic:host`.
- Host mode means jobs execute inside the runner container, not on the physical Docker host.
- The Docker socket is not mounted.
- OpenCode receives a read-only Gitea token. The Gitea write token exists only in the claim and publish steps, when OpenCode is not running.
- All OpenCode agents deny shell commands, subagents, interactive questions, and external-directory access.
- The implementation agent cannot edit `.gitea`, `.ci-agents`, `.opencode`, `AGENTS.md`, or `.gitmodules`. The publisher validates paths again before committing.
- The OpenCode configuration and compiled publisher are baked into `/opt/ci-agents` in the image. Workflows never execute automation code from the checkout.
- Runner capacity and workflow concurrency are both one because OpenAI OAuth refresh tokens can rotate.
- Issue text, comments, repository files, and web results are treated as untrusted input.

Do not use this runner for pull-request workflows, arbitrary repositories, or unrelated jobs.

## Files

```text
.ci-agents/
├── Dockerfile                 Custom Gitea runner image
├── compose.yaml               Runner and one-shot registration services
├── runner-config.yaml         Capacity-one host runner configuration
├── opencode/                  Immutable CI-only OpenCode config and agents
├── src/                       TypeScript claim/run/publish orchestration
├── bin/git-askpass.sh         Immutable Git credential helper
├── package.json
├── package-lock.json
└── .env.example

.gitea/workflows/issue-agents.yml
```

Developers running OpenCode normally do not load `.ci-agents/opencode`. The workflow explicitly selects the image copy with `OPENCODE_CONFIG_DIR=/opt/ci-agents/opencode` while disabling project and external configuration discovery.

## Prerequisites

- Gitea 1.26 or newer. The current instance was verified as 1.26.4.
- Docker Engine with Compose v2, or a compatible Podman deployment.
- A repository-scoped Gitea runner registration token. Do not register this credential-bearing runner at organization or instance scope.
- A dedicated Gitea account or token with repository read access for OpenCode and Gitea MCP.
- An OpenAI account with an active ChatGPT Pro subscription.
- Outbound HTTPS access to OpenAI, Gitea, Context7, Exa, `mcp.grep.app`, npm, Docker Hub, and `gitea.com` while building.

The image pins:

- Gitea Runner `1.0.8`
- OpenCode CLI and SDK `1.17.18`
- Gitea MCP `1.3.0`
- Node.js 24 from the pinned runner's Alpine base (Node.js 22 is used to compile the TypeScript bundle)

## 1. Prepare Configuration

Run from `.ci-agents`:

```bash
cp .env.example .env
```

Edit `.env`:

```dotenv
GITEA_INSTANCE_URL=https://git.krtss.de
GITEA_RUNNER_NAME=olixero-agentic
CI_AGENT_IMAGE=olixero-ci-agent-runner:1.0.0
RUNNER_DATA_DIR=/srv/olixero-ci-agent/runner
OPENCODE_DATA_DIR=/srv/olixero-ci-agent/opencode
CACHE_DIR=/srv/olixero-ci-agent/cache
RUNNER_TOKEN_FILE=./secrets/runner-token
```

Create the bind-mount directories for the fixed container identity `10001:10001`:

```bash
sudo install -d -o 10001 -g 10001 -m 0700 \
  /srv/olixero-ci-agent/runner \
  /srv/olixero-ci-agent/opencode \
  /srv/olixero-ci-agent/cache
```

Create the temporary registration-token file:

```bash
install -d -m 0700 secrets
install -m 0600 /dev/null secrets/runner-token
```

Paste one Gitea runner registration token into `secrets/runner-token`. The directory and `.env` are ignored by Git.

## 2. Build The Runner Image

```bash
docker compose build --pull runner
```

The build verifies the official SHA-256 checksum for the architecture-specific Gitea MCP binary. Both `linux/amd64` and `linux/arm64` are supported.

## 3. Register The Runner Once

```bash
docker compose --profile register run --rm register
```

Confirm in Gitea that the runner is online or idle and has exactly this label:

```text
agentic:host
```

After successful registration, erase the reusable registration token while leaving the file present for Compose validation:

```bash
: > secrets/runner-token
chmod 0600 secrets/runner-token
```

The registration itself persists in `${RUNNER_DATA_DIR}/.runner`.
The one-shot registration container runs as root only so it can read the mode-`0600` Compose secret, then changes `.runner` ownership to the daemon identity `10001:10001`. The long-running service remains non-root.

## 4. Authenticate OpenCode With ChatGPT Pro

Do this while the runner is stopped or before its first start. The interactive helper uses the same image, UID, environment, and OpenCode data mount as the daemon:

```bash
docker compose run --rm --no-deps \
  --entrypoint /usr/local/bin/opencode \
  runner auth login \
  --provider openai \
  --method "ChatGPT Pro/Plus (headless)"
```

OpenCode prints a URL and device code:

```text
Go to: https://auth.openai.com/codex/device
Enter code: ...
Waiting for authorization...
```

Open the URL on another computer, sign in to the intended Pro account, enter the code, approve access, and wait for the container to report success. No browser or inbound callback port is needed on the homelab host.

The credential is stored on the host at:

```text
${OPENCODE_DATA_DIR}/opencode/auth.json
```

Verify that it is owned by `10001:10001` with mode `0600`:

```bash
sudo stat -c '%u %g %a %n' \
  /srv/olixero-ci-agent/opencode/opencode/auth.json
```

Verify credential discovery:

```bash
docker compose run --rm --no-deps \
  --entrypoint /usr/local/bin/opencode \
  runner auth list
```

List subscription models:

```bash
docker compose run --rm --no-deps \
  --entrypoint /usr/local/bin/opencode \
  runner models openai
```

The checked-in agents use `openai/gpt-5.4`. If that model is not listed, update the `model` fields in `opencode/opencode.json` and `opencode/agents/*.md`, rebuild the image, and repeat the smoke test.

Make one live request:

```bash
docker compose run --rm --no-deps \
  --entrypoint /usr/local/bin/opencode \
  runner run --model openai/gpt-5.4 \
  "Reply with exactly: OPENCODE_CI_AUTH_OK"
```

OpenCode automatically refreshes access tokens and writes rotated refresh tokens back to this mount. Do not restore a static credential before jobs, copy Codex's `~/.codex/auth.json`, or put `auth.json` in Gitea secrets, caches, images, or artifacts.

To reauthenticate later:

```bash
docker compose stop runner
docker compose run --rm --no-deps \
  --entrypoint /usr/local/bin/opencode \
  runner auth login \
  --provider openai \
  --method "ChatGPT Pro/Plus (headless)"
docker compose up -d runner
```

## 5. Configure Gitea Repository Secrets And Variables

Create a dedicated read-only personal access token for the account used by OpenCode. It needs to read this repository, issues, comments, pull requests, and source. It must not be able to write repository content, comments, labels, or pull requests.

Create a second token for a dedicated CI bot account. It needs to write repository branches, issue comments and labels, and pull requests. It must be a normal bot PAT rather than Gitea's built-in Actions token: Gitea suppresses workflow triggers caused by its Actions identity, while pull requests created by the normal bot must trigger the separate test workflow.

Add these repository Actions secrets:

| Secret | Required | Purpose |
|---|---:|---|
| `CI_AGENT_READ_TOKEN` | Yes | Read-only Gitea REST, Git fetch, and Gitea MCP access |
| `CI_AGENT_WRITE_TOKEN` | Yes | Claim labels/comments, push generated branches, and create or update pull requests |
| `CONTEXT7_API_KEY` | Recommended | Higher Context7 limits; may be empty if anonymous access is sufficient |

The workflow passes `CI_AGENT_WRITE_TOKEN` only to immutable claim and publish code from the runner image. OpenCode receives only `CI_AGENT_READ_TOKEN`.

Add the repository Actions variable `CI_AGENT_ALLOWED_ACTORS` as a comma-separated list of Gitea logins allowed to trigger agents:

```text
alice,bob
```

If this variable is empty, any user who can add repository labels can trigger an agent run.

## 6. Create Labels

Create these repository labels exactly:

| Label | Required | Behavior |
|---|---:|---|
| `agent:plan` | Yes | Starts planning and is removed when claimed |
| `agent:implement` | Yes | Starts implementation and is removed when claimed |
| `agent:generated` | Recommended | Added to generated pull requests when present |
| `agent:blocked` | Recommended | Added to issues after a failed run when present |
| `agent:plan-ready` | Recommended | Added after an accepted plan when present |

Optional result labels are best-effort. Their absence does not fail a successful run.

## 7. Start The Runner

```bash
docker compose up -d runner
docker compose logs -f runner
```

The main runner service does not mount the registration-token secret and has no Docker socket. Verify in Gitea that it is attached only to the Olixero repository, not to an organization or the whole instance.

## Operation

### Plan an issue

1. Create or update an issue with the complete feature requirements.
2. Add `agent:plan`.
3. The workflow removes the trigger label and maintains one status comment.
4. A planning agent creates a plan and an independent reviewer accepts it or requests revisions.
5. After at most three review cycles, the accepted plan is persisted in one bot-authored comment with a hidden digest marker.

If the issue or default branch changes before publishing, the result is rejected as stale. Re-add `agent:plan`.

### Implement an accepted plan

1. Ensure the issue has an accepted CI-agent plan comment.
2. Add `agent:implement`.
3. The implementation agent edits a stable branch named `agent/issue-<number>-p<digest>`.
4. An independent reviewer accepts the diff or sends it back for revision, up to three cycles.
5. The immutable publisher validates paths, commits without hooks, pushes without force, and creates or updates one pull request.
6. The normal PR workflow runs build and tests on a runner that has no OpenAI OAuth credential.

Changing the issue after planning invalidates the accepted plan. Run `agent:plan` again before implementation.

### Retry a failure

Inspect the status comment and workflow log, correct the issue, remove `agent:blocked` if desired, and re-add the trigger label. Stable markers, branch names, and PR lookup prevent normal retries from creating duplicate comments or pull requests.

## Updating The Automation

All active automation is baked into the image. After changing `.ci-agents`:

```bash
npm ci
npm run check
docker compose build --pull runner
docker compose up -d --force-recreate runner
```

Run the npm commands from `.ci-agents`. Increment `CI_AGENT_IMAGE` for deployments where retaining previous images is useful.

Never configure the workflow to execute `.ci-agents/src`, install dependencies from the checkout, or load `.ci-agents/opencode` directly. The image copy is the trust boundary.

## Troubleshooting

Check the runner:

```bash
docker compose ps
docker compose logs runner
```

Check OpenCode authentication:

```bash
docker compose run --rm --no-deps \
  --entrypoint /usr/local/bin/opencode \
  runner auth list
```

Check MCP startup with the workflow environment available:

```bash
docker compose run --rm --no-deps \
  -e OPENCODE_CONFIG_DIR=/opt/ci-agents/opencode \
  -e OPENCODE_DISABLE_PROJECT_CONFIG=true \
  -e OPENCODE_DISABLE_EXTERNAL_SKILLS=true \
  -e GITEA_SERVER_URL=https://git.krtss.de \
  -e GITEA_READ_TOKEN='<read-only-token>' \
  -e CONTEXT7_API_KEY='<optional-key>' \
  --entrypoint /usr/local/bin/opencode \
  runner mcp list
```

Do not place tokens directly in persistent Compose files or shell history. The final command above is diagnostic syntax; prefer a temporary environment file with mode `0600`.

If OpenCode reports that `ChatGPT Pro/Plus (headless)` is unavailable, confirm the image version, leave default plugins enabled, rebuild, and check the interactive method list with `opencode auth login --provider openai`.