docs(okf): record CI/CD, AI review, release and secrets decisions
PR Check / Dockerfile lint (droast) (pull_request) Skipped
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / ESLint (pull_request) Successful in 36s
PR Check / Typecheck (pull_request) Successful in 38s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 5s
PR Check / Dependency audit (pull_request) Successful in 9s
PR Check / AI code review (opencode) (pull_request) Failing after 13s

Four new decision documents covering the pipeline work: layering,
AI review setup (provider prefix, v2 CLI, env-only auth, verdict
gate), release engineering (release-please manifest mode), and the
Snyk pause with the token scope policy. Index grouped, log extended,
open questions updated.
This commit is contained in:
Noel Sabia committed 2026-10-18 18:19:59 +02:00
1 parent c70f5d7963
commit 7bf649cba6
8 files changed
+302 -2

No files matched your search

+70
View File
@@ -0,0 +1,70 @@
---
type: Decision
title: AI code review setup
description: The review job runs opencode with the opencode-go plan 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
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, review job
- id: go-plan
resource: https://opencode.ai/v2/docs/console/go/
title: OpenCode Go plan documentation
---
# Decision
The review job installs opencode v2 from the dedicated v2 installer,
authenticates with `OPENCODE_API_KEY` from the environment only, runs
`opencode-go/deepseek-v4-pro#max` (covered by the Go plan subscription,
no per-token cost), denies `edit`/`shell`/`webfetch`/`websearch` via a
global permission config written outside the checkout, and posts the
review as a PR comment only if the output ends with a `VERDICT:` line.
# Why each piece
| Piece | Why |
|---|---|
| Provider prefix `opencode-go`, not `opencode` | `opencode` is the pay-per-call Console gateway; the Go plan lives under its own provider id. The wrong prefix failed every run with "Insufficient account funds". |
| The v2 installer (`/v2/install`) | The classic installer ships OpenCode 1.x (v1.19.3 on arm64), which cannot resolve model variants and failed with `ProviderModelNotFoundError` for `#max`. |
| Env-only auth, no `opencode.json` in the checkout | A config file in the workspace holds the API key in plaintext where the review agent can read it; a malicious PR diff could prompt-inject the agent into quoting the key in the publicly visible review comment. Environment variables are invisible to file reads. |
| Deny write tools via a global config outside the checkout | Headless runs cannot answer permission prompts; denials prevent both hangs and repo modification. The config file itself holds no secret, so its location leaks nothing. |
| Verdict line as the posting gate | `opencode` can exit non-zero after a fully completed review (observed: benign permission denials). A completed review always ends with a verdict line; error dumps never do. The verdict, not the exit code, decides whether a comment is posted. |
| `--print-logs` | Provider and auth errors otherwise die inside the captured output file, invisible in the job log. |
| Diff passed as a file, lockfile excluded | The diff as a CLI argument exceeded `MAX_ARG_STRLEN` (128 KiB per argument; the diff was 190 KB, mostly `pnpm-lock.yaml`). The agent reads `.pr-review-diff.patch` with its file tools. |
# The review prompt
The prompt names the stack (Nuxt 4 frontend, Go backends to come), lists
what the other CI jobs already catch so the model does not repeat them,
and focuses on SSR/hydration pitfalls, reactivity bugs, injection and
authz gaps, runtime-config leaks, and Go error/concurrency hygiene. It
prescribes the output format (`[BLOCKER]/[WARN]/[NIT] file:line`) and
derives the verdict from the findings, so the gate and the prompt agree.
# Evidence
* First real review on PR #5 (2026-10-18): produced five findings,
including a genuine regression in the workflow itself (a lost
`chmod +x` on the droast binary), verified upstream release assets and
the v2 permission schema live, and returned `VERDICT: REQUEST_CHANGES`.
* Fresh-container replica test (node:22-bookworm, key-only auth)
reproduced the CI failure exactly, then confirmed the v2 + `#max` fix
before it was pushed.
# Not verified
* Whether `#max` still resolves after a future CLI upgrade — the variant
list comes from the model catalog, not a contract.
* Long-run behaviour of Go plan usage windows ($3 per 5 hours for
DeepSeek V4 Pro) under real review frequency.
# Revisit when
* A PR review fails again with a new error class — check the provider
prefix, the CLI version, and the usage limits first; they caused every
failure so far.
* Go Plus or pay-as-you-go balance becomes relevant.
+4
View File
@@ -1,5 +1,9 @@
# 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.
* [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.
* [Dev container shape](dev-container-shape.md) - The source is bind-mounted into a container that already holds the dependencies, and the dev server runs as the image's `node` user.
* [Build layer order](build-layer-order.md) - Why the manifests are copied before the source, and what invalidates what.
* [Build context filter](build-context-filter.md) - What `.dockerignore` may exclude, and the one thing it must never exclude.
@@ -0,0 +1,74 @@
---
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,
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.
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.
# 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
| 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` in a step, not 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.
+64
View File
@@ -0,0 +1,64 @@
---
type: Decision
title: Release engineering
description: Releases are produced by release-please in manifest mode, driven by conventional commits, with the message format enforced at commit time by commitizen.
tags: [decision, release, release-please, ci]
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: config
resource: release-please-config.json
title: release-please configuration
- id: manifest
resource: .release-please-manifest.json
title: release-please manifest
- id: workflow
resource: .gitea/workflows/release-please.yml
title: release-please workflow
---
# Decision
On every push to `main`, release-please (manifest mode) collects
conventional commits, derives the next version, and opens a release PR
that bumps `package.json`, updates `CHANGELOG.md` and moves the manifest
forward. Merging that PR creates the release. The message format that
feeds this machine is enforced locally by the commitizen pre-commit hook.
# Why
* **Manifest mode** (config JSON + manifest JSON) over inline
`release-type` in the workflow: the configuration becomes part of the
repository, reviewable in PRs, instead of buried in workflow YAML.
* **Plain tags** (`v1.0.0`, `include-component-in-tag: false`):
single-package repository; component-prefixed tags would be noise.
* **A `version` field in `package.json`**: the `node` release type reads
it; without the field the release machinery cannot track anything.
* **Enforcement at commit time**: a non-conventional message is not an
error release-please reports — it just silently produces no release.
Commitizen turns that silent failure into a blocked commit.
# How a release happens, end to end
1. Work lands on branches as conventional commits (`feat:`, `fix:`,
`chore:`, …), enforced by the local hook.
2. Merge to `main` → release-please opens/updates a release PR
(`chore(main): release …`).
3. Merge the release PR → version bumped, changelog written, tag
`vX.Y.Z` created.
# Not verified
* The first release PR end to end — needs at least one `feat:`/`fix:`
commit on `main` after the workflow merge.
* That `RELEASE_PLEASE_TOKEN_CV_SITE_NUXT` carries the `write:issue`
scope the same way `PR_GITEA_TOKEN` needed it; the previous failure
was an immediate API rejection consistent with a scope problem.
# Revisit when
* A second package appears in the repository (then
`include-component-in-tag` and `separate-pull-requests` matter).
* A release must trigger a deploy — the workflow gains a step after
`release_created` is set.
@@ -0,0 +1,51 @@
---
type: Decision
title: Snyk paused, quotas and secrets policy
description: The Snyk job stays in the workflow but is disabled via `if: false` - the free plan quota was the binding constraint - and every Gitea token secret must carry the write:issue scope.
tags: [decision, security, ci, snyk]
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, snyk job
---
# Decision
1. The Snyk job remains in `pr-checker.yml` with `if: false` — skipped,
not deleted. All the arm64/npm-CLI engineering is preserved for the
day it is re-enabled.
2. When re-enabled, it should not run on every push; a schedule or a
ready-for-review gate fits the quota better.
3. Gitea API tokens used by workflow secrets must have `issue`
read+write **and** `repository` read+write, and must not be
public-only. One well-scoped token serves both the AI review comment
posting and release-please.
# Why
* The Snyk free plan grants a small monthly test budget; the pipeline
would burn two tests per PR push. The job failed on its first runs for
two independent reasons (an amd64-only container image, then the
workspace-detection error) before the quota question even arose — the
pause is about quota, the fixes are about portability.
* The `write:issue` scope was discovered the hard way: posting a PR
comment goes through Gitea's issues API, and a token with only
`write:repository` fails with HTTP 403 naming the missing scope. The
error text is the diagnostic — the comment-posting step now prints
status code and response body on failure instead of `curl -sf`
silence.
# Not verified
* Whether the current `RELEASE_PLEASE_TOKEN_CV_SITE_NUXT` value carries
the correct scopes — its failure signature suggested it did not.
# Revisit when
* The quota constraint changes (paid tier, or a schedule-based scan
makes the budget predictable).
* Gitea adds fine-grained token scopes that separate "comment on PR"
from "write issues".
+26
View File
@@ -4,13 +4,39 @@ okf_version: "0.2"
# Start here
This bundle explains the Nuxt repository: how it is developed, checked,
released, and what was learned getting there. It is the "why" behind the
config files — the configs say what, these documents say why.
* [Open questions](open-questions.md) - What is still undecided for the Nuxt site.
* [Update log](log.md) - History of changes to this bundle.
# Decisions
## 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.
* [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.
## Docker and development environment
* [Dev container shape](decisions/dev-container-shape.md) - The source is bind-mounted into a container that already holds the dependencies, and the dev server runs as the image's `node` user.
* [Build layer order](decisions/build-layer-order.md) - Why the manifests are copied before the source, and what invalidates what.
* [Build context filter](decisions/build-context-filter.md) - What `.dockerignore` may exclude, and the one thing it must never exclude.
* [Repository and compose layout](decisions/repo-and-compose-layout.md) - The Dockerfiles live with the app; the stack is assembled in `Local_Development`.
* [Mockup layout](decisions/mockup-layout.md) - One `DESIGN.md` per screen, with the screenshot and the source embedded.
# The one-paragraph history
The repository started as the Nuxt app shell. Docker development (dev
container, layer order, context filter) came first, then a single day of
CI/CD work built the PR pipeline layer by layer — lint, typecheck,
secret scan, dependency audit, Dockerfile lint, AI review — fixing one
real failure per layer as it appeared (wrong provider account, wrong
CLI major version, arm64-hostile vendor images, a silently-skipping
`hashFiles`, a prompt-injectable credential file), then wired releases
via release-please and locked the message format with pre-commit hooks.
The pipeline now fails loudly, posts only real reviews, and needs no
human faith to operate.
+7
View File
@@ -1,5 +1,12 @@
# Update Log
## 2026-10-18 (later — CI/CD and releases)
* **Creation**: Recorded the [PR pipeline layering](decisions/pr-pipeline-layering.md) — three layers (pre-commit, Gitea Actions, AI review), the cost rule that assigns checks to layers, and the failure modes the pipeline was designed against.
* **Creation**: Recorded the [AI review setup](decisions/ai-review-setup.md): the `opencode-go` provider prefix (the wrong one failed every run with "Insufficient account funds"), the v2 installer (v1 cannot resolve model variants), env-only auth after the prompt-injection finding, the read-only permission set, and the verdict line as the posting gate.
* **Creation**: Recorded [release engineering](decisions/release-engineering.md): release-please in manifest mode, plain `v`-tags, the `version` field requirement, and why conventional commits are enforced at commit time.
* **Creation**: Recorded [Snyk paused and secrets policy](decisions/snyk-paused-and-secrets-policy.md): quota-paused job kept in the workflow, and the `write:issue` scope requirement for all workflow tokens (learned from a 403 that named its missing scope).
* **Update**: Rewrote [index](/index.md) to group Docker-era and CI-era decisions and added a one-paragraph history.
## 2026-10-18
* **Creation**: Established the Nuxt bundle [index](/index.md) and the [decisions](/decisions/index.md) index.
* **Decision**: Recorded the [dev container shape](/decisions/dev-container-shape.md) — source bind-mounted, dependencies in the image, run as the image's `node` user.
+6 -2
View File
@@ -4,15 +4,19 @@ title: Open questions
description: Decisions still to make for the Nuxt site, with what needs each answer.
tags: [decision, open]
status: draft
generated: { by: opencode/deepseek-v4.1-flash, at: 2026-10-18T12:41:52Z }
generated: { by: opencode-go/glm-5.3-flash, at: 2026-10-18T12:41:52Z }
---
| Question | Needed by | Default if nobody decides |
|---|---|---|
| Shape of the production image: a runnable Node server, or static `.output/public/` files for the gateway to embed | the next Dockerfile step | None. The empty `Dockerfile` stays empty. |
| Shape of the production image: a runnable Node server, or static `.output/public/` files for the gateway to embed | the next Dockerfile step | None. The empty `Dockerfile` stays empty — and until it holds real instructions, the droast job will fail on it. |
| How the compose service mounts the source: the whole repository plus a volume for `node_modules`, or only the directories that get edited | finishing `Local_Development/docker-compose.yml` | None. The compose file is not yet valid. |
| Which pnpm version the production image pins | writing the production image | The same as dev, 11.26.0. |
| 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. |
| Whether the Go plan's per-model usage windows ($3 per 5 hours for DeepSeek V4 Pro) survive real review frequency, or the review model must move to `deepseek-v4.1-flash` ($80 window) | first quota-limited review | Switch to flash. |
# The mount trade-off, in detail