Merge remote-tracking branch 'origin/main' into feat/docs_registrys
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m6s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 6s
PR Check / Dependency audit (pull_request) Failing after 8s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 5s

# Conflicts:
#	OKF_Nuxt/log.md
This commit is contained in:
Noel Sabia committed 2026-10-31 19:51:00 +01:00
commit c00db55f98
12 files changed
+388 -255

No files matched your search

+5 -1
View File
@@ -3,7 +3,7 @@ type: Decision
title: AI code review setup
description: The review job runs opencode with a cheap medium-effort opencode-go model, env-only auth, a read-only permission set, and posts only reviews that end with a verdict line.
tags: [decision, ci, ai, opencode, security]
status: draft
status: deprecated
generated: { by: opencode-go/glm-5.3-flash, at: 2026-10-18T16:05:00Z }
verified: { by: human:noel, at: not yet }
sources:
@@ -15,6 +15,10 @@ sources:
title: OpenCode Go plan documentation
---
> Superseded by [PR-Agent for Gitea reviews](pr-agent.md) on 2026-10-30.
> The opencode job was removed from `pr-checker.yml`; this document remains
> as the record of the earlier setup and the failures it fixed.
# Decision
The review job installs opencode v2 from the dedicated v2 installer,
+2 -1
View File
@@ -1,7 +1,8 @@
# Decisions
* [PR pipeline layering](pr-pipeline-layering.md) - What runs pre-commit, what runs in Gitea Actions, what the AI review does, and the cost rule that decides.
* [AI review setup](ai-review-setup.md) - Plan model, env-only auth against prompt injection, read-only agent, and the verdict line as the posting gate.
* [PR-Agent for Gitea reviews](pr-agent.md) - A pinned webhook server replaces the per-PR opencode job; internal-only, scoped bot, OpenCode Go model.
* [AI review setup (opencode)](ai-review-setup.md) - Superseded 2026-10-30; kept for the env-only auth and verdict-gate reasoning.
* [Vulnerability audit policy](vulnerability-audit-policy.md) - Blocking audit, reviewed ignore-list for unfixable advisories, and the pnpm-11 settings home.
* [Release engineering](release-engineering.md) - release-please in manifest mode, conventional commits as input, message format enforced at commit time.
* [Snyk paused and secrets policy](snyk-paused-and-secrets-policy.md) - Why the job is skipped rather than deleted, and the token scopes every workflow secret needs.
+119
View File
@@ -0,0 +1,119 @@
---
type: Decision
title: PR-Agent for Gitea reviews
description: A pinned PR-Agent service inside the Gitea compose stack 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: gitea-compose
resource: /home/noel/self-hosted/gitea/docker-compose.yml
title: Gitea compose stack, pr-agent service
- id: operations
resource: OKF_Nuxt/pr-agent.md
title: PR-Agent operations and configuration
- 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`, as the `pr-agent` service in the Gitea compose
stack. It attaches to the existing `gitea_gitea` Docker network and
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 service
definition lives in `/home/noel/self-hosted/gitea/docker-compose.yml`; the
operator guide is [PR-Agent operations](../pr-agent.md).
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/gitea/pr-agent.env` (mode
600) on `server0`. The repository contains the decision and the operator
guide, never the token, webhook secret or model key.
# Evidence
* 2026-10-30: a direct `glm-5.3-flash` call through the handler returned
`OK`, and `/review` on PR #28 posted a PR Reviewer Guide through the Gitea
comment API. The key is set only in `gitea/pr-agent.env`.
# Not verified
* Whether the model finds the same class of issues as the opencode prompt on
larger diffs. The first review found none; `glm-5.3` remains 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
a 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 in the Gitea
compose file and run `docker compose up -d pr-agent` from that directory.
* Review volume makes the container's memory limit tight, or Gitea adds a
role that can comment without push access.
+11 -6
View File
@@ -26,8 +26,8 @@ Every pull request is checked by three layers, ordered by cost:
in one job (one install, cached pnpm store), gitleaks over full
history, pnpm audit (blocking), droast Dockerfile lint, Snyk
(currently disabled).
3. **AI code review** (per PR push): opencode with a plan-covered model,
verdict-based, posted as a PR comment.
3. **AI code review** (on PR open, or on a slash command): the PR-Agent
webhook server, posted as a PR comment.
The split rule: anything that finishes in seconds and auto-fixes goes in
pre-commit; anything slow, network-bound or quota-bound goes in CI; anything
@@ -45,15 +45,16 @@ already passed the deterministic gates.
# Caching
Two caches, both served by the runner's own cache server (no external
service, entries stay on the home server):
One cache, served by the runner's own cache server (no external service,
entries stay on the home server):
* **pnpm store**, keyed on the store layout version (v11) and a `sha256sum`
of `pnpm-lock.yaml`. Installs hardlink from the store instead of
downloading tarballs again. The key is built in a shell step because
`hashFiles()` evaluates empty in this act runner.
* **opencode binary**, keyed on the pinned CLI version (`~/.opencode/bin`).
Small next to the model call, but it removes a network fetch per review.
The opencode binary cache is gone with the opencode job. PR-Agent is a
long-running container on `server0`, so a review no longer downloads a CLI.
Lint and typecheck also share one job: same image, same lockfile, same
install. Splitting them duplicated the install and made both compete for
@@ -71,6 +72,10 @@ exposure in the review setup — each fixed where it was cheapest.
# Failure modes deliberately designed against
The opencode-specific rows are historical since the review moved to
[PR-Agent](pr-agent.md); they are kept because the failure classes still
apply to any review implementation.
| Failure seen | Guard now in place |
|---|---|
| Error logs posted as review comments | Posting gate is the output contract (a `VERDICT:` line), not the exit code |
+3 -1
View File
@@ -11,6 +11,7 @@ config files — the configs say what, these documents say why.
* [Open questions](open-questions.md) - What is still undecided for the Nuxt site.
* [Backend endpoints](backend-endpoints.md) - The smallest API the frontend needs from the Go gateway: health, chapters, metrics, knockdown, events.
* [Profile data](profile.md) - The LinkedIn export behind the terminal chapters, what is real vs mock, and how to refresh it.
* [PR-Agent operations](pr-agent.md) - The Gitea-side review service: configuration, commands, logs and model.
* [Future updates](future-updates.md) - Pipeline improvement backlog with effort estimates, not yet decided.
* [Update log](log.md) - History of changes to this bundle.
@@ -19,7 +20,8 @@ config files — the configs say what, these documents say why.
## CI/CD and releases (2026-10-18)
* [PR pipeline layering](decisions/pr-pipeline-layering.md) - Three layers: pre-commit for cheap deterministic checks, Gitea Actions for thorough ones, AI review for judgment.
* [AI review setup](decisions/ai-review-setup.md) - Plan model, env-only auth against prompt injection, read-only agent, verdict line as the posting gate.
* [PR-Agent for Gitea reviews](decisions/pr-agent.md) - A pinned review service inside the Gitea compose stack replaces the per-PR opencode job; internal-only, scoped bot, OpenCode Go model.
* [AI review setup (opencode)](decisions/ai-review-setup.md) - Superseded 2026-10-30; kept for the env-only auth and verdict-gate reasoning.
* [Vulnerability audit policy](decisions/vulnerability-audit-policy.md) - Blocking audit; reviewed ignore-list for unfixable advisories in pnpm-workspace.yaml.
* [Release engineering](decisions/release-engineering.md) - release-please in manifest mode; conventional commits enforced at commit time.
* [Snyk paused and secrets policy](decisions/snyk-paused-and-secrets-policy.md) - Quota-paused job kept in place; `write:issue` scope required on every workflow token.
+21
View File
@@ -9,6 +9,27 @@
* **Confirmation**: Logged in and pushed by hand - push access works. The registry is **Gitea's built-in container registry** ([docs.gitea.com/usage/packages/container](https://docs.gitea.com/usage/packages/container/)), not a separately deployed component: it is served on the Gitea host, and the `/cv_website/` path segment is the organisation namespace. This is the default - no Registry/Harbor to stand up, nothing to reinvent. Host corrected in the entry above; see [Publishing images to the own registry](decisions/registry-publishing.md).
## 2026-10-30 (PR-Agent moved into the Gitea compose stack)
* **Refactor**: the `pr-agent` service now lives in `/home/noel/self-hosted/gitea/docker-compose.yml` with `/home/noel/self-hosted/gitea/pr-agent.env`. The separate `/home/noel/self-hosted/pr-agent` stack and the unused `/opt` operator-access scripts were removed; the service is managed with the Gitea stack.
* **Docs**: the operator README moved to [PR-Agent operations](pr-agent.md). The decision, index and update log point at the new topology.
* **Evidence**: after the move, the container is healthy, a signed webhook from the Gitea container returns 200, and a direct `glm-5.3-flash` call returns `OK`.
## 2026-10-30 (PR #28: lockfile and PR-Agent routing repaired)
* **Fix**: `pnpm-lock.yaml` - merging `main` left the lockfile at `@nuxt/icon` 2.6.0 while `package.json` asked for 2.6.2, so `pnpm install --frozen-lockfile` aborted in CI. The lockfile now resolves 2.6.2.
* **Fix**: `pnpm-workspace.yaml` - `seroval` 1.6.9 was the two moderate audit findings (GHSA-f86p-h4j2-7qgj, GHSA-9wx9-5pv9-3349). The patched 1.6.11 is forced through `overrides`; the blocking audit now reports only two low-severity advisories and passes the moderate gate.
* **Fix**: PR-Agent model routing - OpenCode Go rejects requests without `x-opencode-session`; `LITELLM__EXTRA_HEADERS` now supplies it, and the fallback keeps the `openai/` prefix. Auto commands are `/describe` and `/review`; `/improve` is on demand. A dummy-key call reaches the provider's auth check instead of failing on the missing header.
* **Evidence**: the key was wired into the live `.env`; a direct `glm-5.3-flash` call returned `OK`, and `/review` on PR #28 posted a PR Reviewer Guide (no findings). The failed-review comment was removed.
* **State**: the key is set only in `gitea/pr-agent.env`; the first `/review` posted on PR #28 with no findings.
## 2026-10-30 (PR-Agent replaces the opencode review job)
* **Decision**: [PR-Agent for Gitea reviews](decisions/pr-agent.md) - a pinned `pragent/pr-agent:0.49.0-gitea_app` container on `server0` reviews PRs through the Gitea bot user `pr-agent`; the endpoint stays on the `gitea_gitea` Docker network.
* **Update**: [pr-checker.yml](../.gitea/workflows/pr-checker.yml) - removed the `review` job, the opencode installer and the verdict-posting step. PR-Agent now runs `/describe` and `/review` on PR open/reopen and answers slash commands.
* **Creation**: `deploy/pr-agent/` (later removed; the service now lives in the Gitea compose stack) - compose service, example environment and operator README. The real `.env` lived only at `/home/noel/self-hosted/pr-agent/.env` (mode 600) on `server0`.
* **State**: the container is running and the webhook signature path is verified. Gitea gained `[webhook] ALLOWED_HOST_LIST = private:3000` (one restart, healthy) and the repository has a signed webhook. The OpenCode Go API key was still missing at commit time, so no model call or real review has run yet.
## 2026-10-27 (release-please still never tagged: the deleted head branch)
* **Fix**: [release-please-config.json](../release-please-config.json) gained `"changelog-host": "https://git.noelsabia.dev"` - the changelog compare links were generated against `github.com/CV_Website/CV_Site_Nuxt`, a host this repository does not live on. Root cause of the missing tags: **Gitea rewrites `head.ref` to `refs/pull/<n>/head` when the merged PR's branch is deleted**, and release-please parses that field as the release branch, so `BranchName.parse` fails and the release is dropped - silently, exit code 0. Evidence: run 143 (task 475) logs `✖ Bad branch name: refs/pull/22/head` right after `Found pull request #22`, then `Expected 1 releases, only found 0`; #22 did carry `autorelease: pending`. The repository deleted every merged branch (`default_delete_branch_after_merge: true`); it is `false` now. Four versions (1.1.0-1.4.0) were consumed by the manifest with no tag ever created, so the release baseline has to be restored by hand. See [Release engineering](decisions/release-engineering.md).
+2 -1
View File
@@ -16,7 +16,8 @@ generated: { by: opencode-go/glm-5.3-flash, at: 2026-10-18T12:41:52Z }
| Whether these decisions stay in this bundle or fold into the sibling `OKF_CV_Website` bundle, which already describes the frontend at design level | after the production image exists | None. |
| When and how often Snyk runs once re-enabled: weekly schedule, ready-for-review gate, or per-push | re-enabling the snyk job | Stay disabled. |
| Whether the AI review job should gate merges (required status check on the verdict) or stay advisory | branch protection setup | Advisory. The review comment is information; blocking merges on an AI verdict is a policy choice, not a technical one. |
| How the opencode CLI version in CI gets upgraded: manually bump the pinned 2.0.32, or automate when a new major appears | first review failure after an opencode release | Manual bump. Pinning exists so upgrades are decisions. |
| ~~How the opencode CLI version in CI gets upgraded~~ - **closed** (2026-10-30): the opencode job was removed; the review path is a pinned PR-Agent container. See [PR-Agent for Gitea reviews](decisions/pr-agent.md) | done | — |
| Whether `glm-5.3-flash` through PR-Agent produces acceptable reviews on this repository | first PR after the OpenCode Go key is set | Keep it; `glm-5.3` is the configured fallback. |
| ~~Whether the Go plan's per-model usage windows survive real review frequency, and which model the review should use~~ - **decided** (2026-10-20): review model is `opencode-go/claude-haiku-5-5#medium` in [pr-checker.yml](../.gitea/workflows/pr-checker.yml). Cheap per token, and it has a real `#medium` effort level; `deepseek-v4.1-flash` only exposes low/high/max, so it always paid for maximum reasoning. The earlier pro -> flash switch (two consecutive `Endpoint is unavailable` failures) is in the [log](../log.md) | done | — |
| Removing the two reviewed audit ignores when `node-forge` or `braces` ship patched releases | next dependency update round | Watch for new releases. |
+123
View File
@@ -0,0 +1,123 @@
---
type: Reference
title: PR-Agent operations
description: The Gitea-side pull-request review service, its configuration in the Gitea compose stack, and the commands it answers.
tags: [pr-agent, gitea, operations, ci, ai]
status: draft
generated: { by: opencode-go/deepseek-v4.1-flash, at: 2026-10-30T20:40:00Z }
verified: { by: human:noel, at: not yet }
sources:
- id: gitea-compose
resource: /home/noel/self-hosted/gitea/docker-compose.yml
title: Gitea compose stack, pr-agent service
- id: install
resource: https://docs.pr-agent.ai/installation/gitea/
title: PR-Agent Gitea installation
- id: gitea-egress
resource: https://docs.gitea.com/administration/config-cheat-sheet#webhook
title: Gitea webhook egress allowlist
---
# What runs
PR-Agent is the `pr-agent` service inside the Gitea compose stack on
`server0`. It listens on the internal `gitea_gitea` network at
`http://pr-agent:3000`; no port is published. Gitea calls its signed
webhook at `/api/v1/gitea_webhooks`, and the bot user `pr-agent` posts the
results.
| Piece | Value |
|---|---|
| Service | `pr-agent` in `/home/noel/self-hosted/gitea/docker-compose.yml` |
| Image | `pragent/pr-agent:0.49.0-gitea_app` |
| Config | `/home/noel/self-hosted/gitea/pr-agent.env` (mode 600) |
| Logs | `cd /home/noel/self-hosted/gitea && docker compose logs -f pr-agent` |
| Restart | `cd /home/noel/self-hosted/gitea && docker compose up -d pr-agent` |
| Upgrade | bump the image tag in the compose file, then restart the service |
The service is managed with the same access as the rest of the Gitea
stack. The earlier plan for a separate `/opt/pr-agent` stack and a
restricted `agent` account was not applied; those scripts were removed when
the service moved into this stack. Hardening the Gitea stack's operator
access is a separate change.
# Gitea side
1. Bot user `pr-agent` is a collaborator with write permission on
`CV_Website/CV_Site_Nuxt`. Its personal access token is scoped to
`read:repository`, `write:issue` and `read:user`.
2. The repository webhook sends `push`, `issues`, `pull_request` and
`issue_comment` events, with JSON content type and the shared secret.
3. Gitea's `[webhook] ALLOWED_HOST_LIST` includes `private:3000`. Without
it, Gitea's default egress policy refuses deliveries to the Docker
network.
# Commands
| Trigger | What runs |
|---|---|
| PR opened or reopened | `/describe` and `/review` automatically |
| New push to an open PR | nothing; comment `/review` or `/review -i` |
| Comment `/review`, `/improve`, `/ask` | that command |
`/review -i` reviews only the commits added since the previous review.
`/improve` stays on demand; adding it to the auto list would make a second
model call and a second comment on every PR. Draft PRs are not skipped.
# Configuration
`pr-agent.env` holds the deployment values. The repository never contains
the token, webhook secret, or API key:
```ini
CONFIG__GIT_PROVIDER=gitea
GITEA__URL=http://gitea:3000
GITEA__WEB_URL=https://git.noelsabia.dev
GITEA__PERSONAL_ACCESS_TOKEN=...
GITEA__WEBHOOK_SECRET=...
CONFIG__MODEL=openai/glm-5.3-flash
CONFIG__FALLBACK_MODELS=["openai/glm-5.3"]
CONFIG__CUSTOM_MODEL_MAX_TOKENS=128000
OPENAI__API_BASE=https://opencode.ai/inference/go/openai/v1
OPENAI__KEY=...
LITELLM__EXTRA_HEADERS={"x-opencode-session":"pr-agent"}
GITEA__PR_COMMANDS=["/describe","/review"]
```
OpenCode Go requires the `x-opencode-session` header. The fallback keeps
the `openai/` prefix; a bare `glm-5.3` is treated by LiteLLM as a
provider-less model. `CONFIG__CUSTOM_MODEL_MAX_TOKENS` supplies the context
limit; the effective review budget is capped by PR-Agent's default
`max_model_tokens` of 32000.
The compose service:
```yaml
pr-agent:
image: pragent/pr-agent:0.49.0-gitea_app
container_name: pr-agent
restart: unless-stopped
env_file:
- ./pr-agent.env
environment:
PORT: "3000"
GUNICORN_WORKERS: "2"
mem_limit: 1g
networks:
- gitea
healthcheck:
test: ["CMD", "python", "-c", "import socket; socket.create_connection(('127.0.0.1', 3000), 3).close()"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
```
# Checks
A signed webhook from the Gitea container returns 200, and a direct
`glm-5.3-flash` call returns a completion. A `403` in the Gitea webhook
delivery log means the secret does not match or `ALLOWED_HOST_LIST` is
missing; a `401` from PR-Agent means the signature and secret disagree.
On a model failure, check `docker compose logs pr-agent` and confirm
`OPENAI__KEY` is set in `pr-agent.env`.