Files
CV_Site_Nuxt/OKF_Nuxt/decisions/pr-agent.md
T
Noel Sabia a43134ad83
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m8s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 7s
PR Check / Dependency audit (pull_request) Successful in 8s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 5s
fix(ci): repair PR-Agent model routing
OpenCode Go rejects requests without x-opencode-session, and LiteLLM needs the openai/ prefix on the fallback model. Supply the header through LITELLM__EXTRA_HEADERS, keep the prefixed fallback, and stop auto-running /improve so a PR gets one review plus /describe.
2026-10-30 21:14:15 +01:00

116 lines
5.1 KiB
Markdown

---
type: Decision
title: PR-Agent for Gitea reviews
description: A pinned PR-Agent webhook server on server0 reviews pull requests through a scoped Gitea bot user, replacing the per-PR opencode job.
tags: [decision, ci, ai, gitea, pr-agent, security]
status: draft
generated: { by: opencode-go/deepseek-v4.1-flash, at: 2026-10-30T20:00:00Z }
verified: { by: human:noel, at: not yet }
sources:
- id: compose
resource: deploy/pr-agent/docker-compose.yml
title: PR-Agent compose service
- id: env-example
resource: deploy/pr-agent/.env.example
title: Environment variables, without secrets
- id: pr-checker
resource: .gitea/workflows/pr-checker.yml
title: PR Check workflow, opencode job removed
- id: install
resource: https://docs.pr-agent.ai/installation/gitea/
title: PR-Agent Gitea installation
- id: images
resource: https://hub.docker.com/r/pragent/pr-agent
title: Published gitea_app image tags
- id: gitea-egress
resource: https://docs.gitea.com/administration/config-cheat-sheet#webhook
title: Gitea webhook egress allowlist
---
# Decision
PR-Agent runs as `pragent/pr-agent:0.49.0-gitea_app` in a long-lived
container on `server0`, attached to the existing `gitea_gitea` Docker
network. It publishes no ports. Gitea delivers pull-request and comment
events to `http://pr-agent:3000/api/v1/gitea_webhooks`; the bot user
`pr-agent` posts the result with a scoped personal access token.
The opencode review job is removed from `pr-checker.yml`. PR-Agent runs
`/describe` and `/review` on pull request open/reopen and answers slash
commands in the conversation. Push-triggered re-review is disabled, so a
PR is reviewed once when it opens, not on every push.
The model is OpenCode Go's OpenAI-compatible endpoint:
```text
model openai/glm-5.3-flash
fallback openai/glm-5.3
api base https://opencode.ai/inference/go/openai/v1
```
`CONFIG__CUSTOM_MODEL_MAX_TOKENS=128000` supplies the context limit the
model table does not know; PR-Agent's default `config.max_model_tokens`
still caps the review budget at 32000.
OpenCode Go requires an `x-opencode-session` header. PR-Agent sends the
stable id `pr-agent` through `LITELLM__EXTRA_HEADERS`; without it the
provider rejects the request before it reaches the model.
# Why
* One container replaces a per-PR CLI install, binary cache and prompt
wrapper. The review path is then the same code for every PR.
* PR-Agent owns the Gitea webhook and comment plumbing, including the slash
commands (`/review`, `/improve`, `/ask`) the repository previously had no
way to trigger.
* The webhook endpoint stays on the Docker network. Nothing new is exposed
to the internet, and comment links still use the public Gitea URL.
* The image tag is pinned. A new PR-Agent release is a deliberate change,
not a rollout underneath the repository.
# Gitea configuration
* Bot user `pr-agent` is a collaborator with write permission on
`CV_Website/CV_Site_Nuxt`. The token scopes are `read:repository`,
`write:issue` and `read:user`. Gitea has no comment-only collaborator
role, so write is the narrowest role that can post comments and labels.
* `[webhook] ALLOWED_HOST_LIST = private:3000` is required: Gitea's default
lax egress policy allows public targets but refuses private ones, and the
webhook target is a Docker-network address. The API is reached at
`http://gitea:3000`; `GITEA__WEB_URL=https://git.noelsabia.dev` keeps
published links on the public host.
* The webhook sends `push`, `issues`, `pull_request` and `issue_comment`
events. Only the last two change behaviour today; `push` is kept because
PR-Agent may handle push commands in a later configuration.
* Auto commands are `/describe` and `/review`. `/improve` stays available
on demand; the default auto list would add a second model call and a
second comment to every PR.
* Secrets live only in `/home/noel/self-hosted/pr-agent/.env` (mode 600) on
`server0`. The repository contains the compose file and an example env
file, never the token or webhook secret.
# Not verified
* The OpenCode Go API key was not present when this was committed, so no
model call has completed. A dummy-key call now reaches the provider's
authentication check instead of failing on the missing session header,
so the remaining blocker is the credential. The first PR after the key is
set is the real verification.
* Whether `glm-5.3-flash` handles PR-Agent's structured review output well
enough. `glm-5.3` is configured as the fallback.
* Whether two gunicorn workers and the 1 GB memory limit hold under
concurrent reviews. The host has roughly 2.5 GB available with Gitea and
its runner idle.
* Whether the default review prompt is specific enough for this repository.
A `.pr_agent.toml` with project instructions is deliberately absent until
the first real review shows what it misses.
# Revisit when
* The first review fails, returns unstructured output, or misses the kind
of finding the opencode prompt used to catch.
* A newer `gitea_app` image tag is worth taking; bump the tag and run
`docker compose up -d`.
* Review volume makes the container's memory limit tight, or Gitea adds a
role that can comment without push access.