Files
CV_Site_Nuxt/OKF_Nuxt/decisions/pr-pipeline-layering.md
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

4.3 KiB

type, title, description, tags, status, generated, verified, sources
type title description tags status generated verified sources
Decision PR pipeline layering 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.
decision
ci
gitea-actions
pre-commit
security
draft
by at
opencode-go/glm-5.3-flash 2026-10-18T16:05:00Z
by at
human:noel not yet
id resource title
pr-checker .gitea/workflows/pr-checker.yml PR Check workflow
id resource title
pre-commit .pre-commit-config.yaml 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; 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.