docs(okf): record CI/CD, AI review, release and secrets decisions #7
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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".
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user