viktor/infra
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: CI-compute doctrine — leverage external infra for builds AND tests [ci skip]

Browse source 
Viktor's standing instruction (2026-06-12): lean on external infra as
much as possible for CI — builds, running tests, lint, releases all on
GitHub Actions hosted runners, never on cluster nodes; in-cluster
pipelines only for cluster-touching steps (deploys, terragrunt,
certbot). Also: watch any triggered pipeline chain to completion and
fix failures immediately. Added to AGENTS.md + .claude/CLAUDE.md
CI sections (ADR-0002 companions).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Viktor Barzin 2026-06-12 20:39:27 +00:00
parent 97dcf49b8e
commit bb0f9f59ef
2 changed files with 13 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

13
.claude/CLAUDE.md
View file

@ -26,7 +26,7 @@ Violations cause state drift, which causes future applies to break or silently r
## Instructions
- **"remember X"**: Use `memory-tool store "content" --category facts --tags "tag1,tag2"` (via exec) for persistent cross-session memory. Also update this file + `AGENTS.md` (if shared knowledge), commit with `[ci skip]`. To recall: `memory-tool recall "query"`. To list: `memory-tool list`. To delete: `memory-tool delete <id>`. The native `memory_search` and `memory_get` tools are also available for searching indexed memory files. For **storing** new memories, always use the `memory-tool` CLI via exec.
- **Apply**: Authenticate via `vault login -method=oidc`, then use `scripts/tg` (preferred — handles state decrypt/encrypt) or `terragrunt` directly. `scripts/tg` adds `-auto-approve` for `--non-interactive` applies.
- **New services need CI/CD** and **monitoring** (Prometheus/Uptime Kuma)
- **New services need CI/CD** and **monitoring** (Prometheus/Uptime Kuma). CI = a GHA workflow on the repo's GitHub mirror (build + tests off-infra, ADR-0002); Woodpecker gets a deploy-only pipeline — never an in-cluster build.
- **New service**: Use `setup-project` skill for full workflow
- **Ingress**: `ingress_factory` module. **Auth** (`auth` string enum, default `"required"` — fail-closed). Pick by asking "what gates the app?":
- `auth = "required"` — Authentik forward-auth gates every request. Use when the backend has **no built-in user auth** and Authentik is the only thing standing between strangers and the app (prowlarr, qbittorrent, netbox, phpipam, k8s-dashboard, any admin UI shipped without its own login).
@ -89,6 +89,17 @@ Violations cause state drift, which causes future applies to break or silently r
## CI/CD Architecture — GHA Builds + Woodpecker Deploy
**Doctrine (ADR-0002): leverage external infra for ALL CI compute.** Builds,
tests, lint, and release jobs run on GitHub Actions hosted runners (public
repos: unlimited free; private: 2000 free min/mo) — never on cluster nodes.
In-cluster pipelines are reserved for cluster-touching steps only: Woodpecker
deploys (`kubectl set image`), terragrunt applies, certbot. Do not
(re)introduce in-cluster image builds or CI test runs — the fallback-build
pattern was deliberately removed (clean cut). **Watch what you trigger**:
after any push that fires a build chain, monitor it to completion (GHA run →
Woodpecker deploy → `rollout status`) and fix failures immediately; verify
via live state, not the checkmark. Fleet migration: PRD infra#10 (ADR-0002).
**Owned-app deploy model (build triggers the rollout — 2026-06-02):** For
self-hosted apps **we build** (Forgejo `viktor/<name>` + Dockerfile +
`.woodpecker.yml`), the build pipeline ALSO drives the rollout — atomic +

1
AGENTS.md
View file

@ -90,6 +90,7 @@ Terragrunt-based homelab managing a Kubernetes cluster (5 nodes, v1.34.2) on Pro
- **Public domain**: `viktorbarzin.me` (Cloudflare) | **Internal**: `viktorbarzin.lan` (Technitium DNS)
- **Onboarding portal**: `https://k8s-portal.viktorbarzin.me` — self-service kubectl setup + docs
- **CI/CD**: Woodpecker CI — PRs run plan, merges to master auto-apply all stacks
- **CI compute is external (ADR-0002, 2026-06-12)**: builds, tests, lint, and release jobs run on GitHub Actions hosted runners via each repo's GitHub mirror — never on cluster nodes. In-cluster pipelines exist only for steps that need cluster access (Woodpecker `kubectl set image` deploys, terragrunt applies, certbot). Never add an in-cluster build or test pipeline to any repo; the fallback-build pattern was deliberately removed. After pushing anything that fires a build chain, watch it end-to-end (GHA run → Woodpecker deploy → rollout) before calling the change done — verify live state, not the checkmark.
## Key Paths
- `stacks/<service>/main.tf` — service definition