pal-e-docs

Review: Automate Salt highstate via Woodpecker CI on pal-e-platform merge

review-1615-2026-06-26 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovered during Sprint 5 validation
  • [x] Repo -- ldraney/pal-e-platform
  • [x] User Story -- As a platform operator...
  • [x] Context -- Manual SSH gap after merge
  • [x] File Targets -- present but contains error (see below)
  • [x] Feature Flag -- none (correct, infra automation)
  • [x] Acceptance Criteria -- 4 criteria
  • [x] Test Expectations -- integration test described
  • [x] Constraints -- present, 3 items
  • [x] Checklist -- present
  • [x] Related -- 2 references

Traceability

  • [x] story:WS-S1 label -- "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable"
  • [x] story note verified -- found in project-westside-basketball user-stories section (Superadmin list)
  • [x] arch:salt label -- Salt configuration management component
  • [ ] arch note MISSING -- [SCOPE] Create architecture note arch-salt for the Salt component. No note found via search_notes("arch-salt").
  • [x] Forgejo issue -- ldraney/pal-e-platform#466, open
  • [ ] project page MISSING -- No project-pal-e-platform page exists in pal-e-docs. This is acceptable for now as pal-e-platform is an infra repo without a dedicated project page, but the story references project-westside-basketball which does exist.

File Targets

  • [ ] .woodpecker.yml -- ISSUE: File does not exist. The repo uses a .woodpecker/ directory pattern (contains terraform.yaml and ruby-arch.yaml). The correct target is .woodpecker/salt.yaml (new file, following directory convention).
  • [x] salt/ -- verified: directory exists with bootstrap.sh, master.conf, minion.conf, pillar/, states/ subdirectories. Correctly noted as "no changes to Salt itself."

Repo Placement

OK. Issue is filed on ldraney/pal-e-platform, and the work (adding a Woodpecker pipeline for Salt) lives entirely in pal-e-platform. Single-repo change.

Dependencies

  • Board item #1480 (ldraney/pal-e-platform#453, "Woodpecker CI: tofu plan on PR, apply on merge") -- CLOSED/DONE. This established the Woodpecker CI pattern in pal-e-platform that this ticket extends. The existing .woodpecker/terraform.yaml is the reference implementation.
  • Board item #1104 (forgejo_admin/pal-e-platform#306, arch:salt) -- backlog, "Salt-manage admin-kubeconfig". Related Salt work but not a blocker.
  • Board item #1149 (forgejo_admin/pal-e-platform#332, arch:salt) -- the k3s maxPods Salt ticket is CLOSED, confirms Salt patterns are established in the repo.
  • No blocking dependencies. This ticket is independent.

Acceptance Criteria

  • [x] AC1: "Woodpecker pipeline triggers Salt highstate on edge-proxy after merge to main" -- verifiable via Woodpecker UI
  • [x] AC2: "Pipeline only runs when salt/ directory has changes (path filter)" -- verifiable, but Woodpecker path filter implementation detail should be specified in Constraints (Woodpecker uses when: path: syntax)
  • [x] AC3: "Failure alerts via Woodpecker notification (existing pattern)" -- verifiable, references existing pattern
  • [ ] AC4: "Pipeline uses SSH key to connect to edge-proxy (no password auth)" -- verifiable, but missing detail: which Woodpecker secret name holds the SSH key? Is the secret already provisioned, or does this ticket need to create it? This is a scoping gap.
Overall: criteria are testable but AC4 needs the SSH secret name and provisioning status clarified.

Blast Radius

  • The existing .woodpecker/terraform.yaml pipeline runs on push to main. The new Salt pipeline will coexist as a separate file (.woodpecker/salt.yaml), so no interference.
  • The cross-pillar-review step in the existing terraform pipeline already watches for salt/* changes and creates review issues. Adding a separate Salt pipeline means Salt changes will trigger BOTH the cross-pillar review AND the new Salt pipeline -- this is correct behavior but worth noting.
  • Edge-proxy SSH access via Tailscale is a constraint already noted. The Woodpecker runner pod must have Tailscale access. This is an infrastructure prerequisite that should be verified exists (or flagged as a pre-req).
  • No similar gap exists in other repos -- Salt is only managed in pal-e-platform.

Decomposition Assessment

1 new file (.woodpecker/salt.yaml), 4 acceptance criteria, single repo. Estimated agent work under 5 minutes. No decomposition needed.

Recommendations

  • [BODY] Fix file target path: .woodpecker.yml should be .woodpecker/salt.yaml (new file in the existing .woodpecker/ directory, matching terraform.yaml convention).
  • [BODY] Add to Constraints: specify the Woodpecker secret name for the edge-proxy SSH key, and state whether the secret already exists or must be created as part of this ticket.
  • [BODY] Add to Constraints: "Follow .woodpecker/terraform.yaml clone block and path-filter patterns from this same repo" (currently says "Follow existing .woodpecker.yml patterns in pal-e-services" -- wrong reference).
  • [SCOPE] Create architecture note arch-salt for the Salt configuration management component in pal-e-docs.