Update CI pipeline docs with Kaniko registry architecture decision #99

New issue

Closed

opened 2026-06-04 12:22:58 +00:00 by ldraney · 0 comments

ldraney commented

2026-06-04 12:22:58 +00:00

Owner

Type

Feature

Lineage

Standalone — post-incident documentation from PRs #76-#79, #91 (Kaniko registry oscillation).

Repo

ldraney/landscaping-assistant

User Story

As a developer modifying the CI pipeline
I want the docs to accurately describe the Kaniko pull/push architecture
So that I don't accidentally re-introduce a build_args override that breaks the pipeline

Context

docs/infrastructure-and-pipeline.md is stale after 7 CI-related PRs (#70, #76-#79, #81, #91). The .woodpecker.yaml example is missing the clone step, bundle cache steps, and insecure-registry settings. More critically, there's no documentation of the architectural decision about why Kaniko uses different registry paths for pulls vs pushes — the root cause of 10+ consecutive pipeline failures.

File Targets

docs/infrastructure-and-pipeline.md — update CI Pipeline section, add Kaniko Registry Architecture section, update kustomization.yaml example

Acceptance Criteria

.woodpecker.yaml example matches current config on main
Pipeline mermaid diagram reflects actual step flow (clone → cache → bundle → lint/test → build)
Kaniko Registry Architecture section documents pull/push path split with table
Explicit warning about build_args footgun
kustomization.yaml example shows ArgoCD Image Updater SHA tag entry

Test Expectations

Docs-only change, no code tests needed
Verify examples match actual config: git show main:.woodpecker.yaml

Constraints

Docs only — no code changes in this issue

Checklist

PR opened
No unrelated changes

ldraney/landscaping-assistant #82 — the incident that motivated this

### Type Feature ### Lineage Standalone — post-incident documentation from PRs #76-#79, #91 (Kaniko registry oscillation). ### Repo `ldraney/landscaping-assistant` ### User Story As a developer modifying the CI pipeline I want the docs to accurately describe the Kaniko pull/push architecture So that I don't accidentally re-introduce a `build_args` override that breaks the pipeline ### Context `docs/infrastructure-and-pipeline.md` is stale after 7 CI-related PRs (#70, #76-#79, #81, #91). The `.woodpecker.yaml` example is missing the clone step, bundle cache steps, and `insecure-registry` settings. More critically, there's no documentation of the architectural decision about why Kaniko uses different registry paths for pulls vs pushes — the root cause of 10+ consecutive pipeline failures. ### File Targets - `docs/infrastructure-and-pipeline.md` — update CI Pipeline section, add Kaniko Registry Architecture section, update kustomization.yaml example ### Acceptance Criteria - [ ] `.woodpecker.yaml` example matches current config on main - [ ] Pipeline mermaid diagram reflects actual step flow (clone → cache → bundle → lint/test → build) - [ ] Kaniko Registry Architecture section documents pull/push path split with table - [ ] Explicit warning about `build_args` footgun - [ ] kustomization.yaml example shows ArgoCD Image Updater SHA tag entry ### Test Expectations - [ ] Docs-only change, no code tests needed - [ ] Verify examples match actual config: `git show main:.woodpecker.yaml` ### Constraints - Docs only — no code changes in this issue ### Checklist - [ ] PR opened - [ ] No unrelated changes ### Related - `ldraney/landscaping-assistant #82` — the incident that motivated this