Files
CV_Site_Nuxt/OKF_Nuxt/decisions/pr-pipeline-layering.md
T
Noel Sabia c626cc9c1d
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Canceled after 45s
PR Check / Secret scan (gitleaks) (pull_request) Canceled after 0s
PR Check / Dependency audit (pull_request) Canceled after 0s
PR Check / Dockerfile lint (droast) (pull_request) Canceled after 0s
feat(ci): replace opencode review with PR-Agent
Run PR-Agent as a pinned webhook server on the Gitea Docker network and review on PR open plus slash commands. The per-PR opencode installer and verdict-posting step are removed.

The server-side .env stays outside the repository; deploy/pr-agent/ holds the compose definition and operator notes.
2026-10-30 21:00:53 +01:00

98 lines
4.3 KiB
Markdown

---
type: Decision
title: PR pipeline layering
description: Three layers - pre-commit hooks for cheap deterministic checks, Gitea Actions for thorough checks, an AI reviewer for judgment - and the rule that decides what runs where.
tags: [decision, ci, gitea-actions, pre-commit, security]
status: draft
generated: { by: opencode-go/glm-5.3-flash, at: 2026-10-18T16:05:00Z }
verified: { by: human:noel, at: not yet }
sources:
- id: pr-checker
resource: .gitea/workflows/pr-checker.yml
title: PR Check workflow
- id: pre-commit
resource: .pre-commit-config.yaml
title: Pre-commit guardrails
---
# Decision
Every pull request is checked by three layers, ordered by cost:
1. **Pre-commit hooks** (local, seconds, deterministic): gitleaks, file
hygiene, conventional-commit check, actionlint, eslint --fix on staged
files. A commit that fails here never exists.
2. **Gitea Actions** (per PR push, minutes): ESLint + vue-tsc typecheck
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** (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
that produces judgment rather than a pass/fail is the AI review. Nothing
slow lives in pre-commit — one slow hook gets bypassed with `--no-verify`
once and is dead weight forever.
# Why
Each layer catches what the previous one cannot. Pre-commit sees the commit
before it exists; CI sees the whole PR on a clean machine; the AI review
sees intent, contracts and cross-file consequences that no linter can. The
ordering also protects the budget: the AI review only runs for code that
already passed the deterministic gates.
# Caching
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.
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
the runner's two vCPUs. A future `pnpm build` job reuses the same store
cache key.
# What the pipeline bought us in practice
Recorded so the reasoning survives: during the first week the pipeline
caught leaked secrets in history (gitleaks), a review model configured
against the wrong provider account, a Dockerfile-lint job that silently
never ran (`hashFiles` evaluating empty in the act runner), a review that
completed but exited non-zero, and an attacker-relevant credential
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 |
| Vendor container images without arm64 manifests | Binaries installed arch-aware in `node:22-bookworm`, never vendor CI images |
| `hashFiles()` silently empty in the act runner | File discovery via `find` and cache keys via `sha256sum`, both in shell steps - never workflow expressions |
| Silent advisory failures | `continue-on-error` removed everywhere; a failed check is red |
| Supply-chain (curl-piped binaries) | Pinned versions, checksums pinned in the workflow |
# Not verified
* That the Snyk job still works when re-enabled — it was disabled while
the free quota was the binding constraint.
* That the pipeline behaves on Gitea runner versions other than v0.6.1.
# Revisit when
* A second repository needs the same pipeline (extract a reusable
workflow include).
* The Go plan's usage limits are hit by review traffic.