pal-e-docs

Review: Bug: update-kustomize-tag skipped when CI tests fail

review-882-2026-04-07 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Bug
  • [x] Lineage — Standalone, discovered during CRM incident response 2026-04-07
  • [x] Repo — forgejo_admin/pal-e-platform
  • [ ] User Story — not explicitly stated in issue body (board item has story:PLAT-S2 but that key is invalid)
  • [x] Context — sufficient for a fresh-context agent (pipeline numbers, symptoms, root cause)
  • [ ] File Targets — no explicit file paths listed in the issue. Agent would need to discover them.
  • [ ] Acceptance Criteria — present but first criterion is a design decision ("Option A or Option B"), not a testable condition
  • [ ] Test Expectations — no test commands or assertions specified
  • [x] Constraints — dependencies on Woodpecker behavior are described
  • [ ] Checklist — no discrete execution steps
  • [x] Related — project and deployment-lessons referenced

Traceability

  • [ ] story:PLAT-S2 — NOT FOUND on project-pal-e-platform user-stories section. Valid keys are: story:superuser-deploy, story:superuser-observe, story:superuser-recover, story:superuser-onboard-service, story:superuser-remote-access. Closest match: story:superuser-deploy ("I can deploy infrastructure changes via tofu plan/apply and see them succeed in Woodpecker CI without manual intervention").
  • [ ] arch:woodpecker — label present on board item but no arch-woodpecker note exists in pal-e-docs (search returned zero results).
  • [x] Forgejo issue — #274, open

File Targets

The issue does not list explicit file targets. Reviewer verified the relevant files:
  • [x] pal-e-platform/scripts/woodpecker-update-tag-step.yaml — verified: canonical template exists, line 37-38 shows depends_on: [build-and-push]
  • [x] pal-e-platform/scripts/update-kustomize-tag.sh — verified: deployment script (99 lines, clone/sed/commit/push logic)
  • [x] basketball-api/.woodpecker.yaml — verified: lines 60-82 show update-kustomize-tag step with depends_on: [build-and-push]
  • [ ] Issue body does not specify which files to modify — agent must discover them. [BODY] Add File Targets section.

Repo Placement

AMBIGUOUS. Issue is filed on pal-e-platform, which owns the template and script. However the fix location depends on the unresolved Option A/B decision:
  • Option A (allow deploy when test fails): fix lives in each consumer repo's .woodpecker.yaml (currently only basketball-api) AND the template in pal-e-platform. Multi-repo change.
  • Option B (add alerting for stale tags): fix lives in pal-e-platform only (Prometheus alert rule in terraform).
If Option A, this should be structured as: one PR in pal-e-platform (template update) + one PR per consumer repo. Currently only basketball-api has the step wired.

Dependencies

  • [ ] #254 — "Woodpecker pipeline restart skips deploy steps (missing event:push metadata)" — related but distinct bug affecting the same step. Status: open. Not a blocker but fixing together would be efficient.
  • [ ] #206 — "Rollout: wire update-kustomize-tag step into all 8 app repos" — open. Any template change from this fix must land before rollout continues. Ordering dependency.
  • [ ] #259 — "Woodpecker push-to-main pipelines fail with no steps" — open. Another Woodpecker pipeline issue, potentially related.

Acceptance Criteria

NOT AGENT-ACTIONABLE. The first criterion is "Decision: Option A or Option B" — this requires human judgment, not agent execution. Remaining criteria are conditional on this decision. An agent cannot execute this ticket until:
  • The decision is made by a human.
  • AC is rewritten as concrete, testable statements.
Suggested rewrites after decision:
  • If Option A: "update-kustomize-tag runs when build-and-push succeeds, regardless of test step status" + "template in scripts/woodpecker-update-tag-step.yaml updated to match" + "no regression when all steps succeed"
  • If Option B: "Prometheus alert fires when Harbor image tag is newer than kustomize overlay tag for >10 minutes" + "Alert documented in deployment-lessons"

Blast Radius

  • Current scope: Only basketball-api has the update-kustomize-tag step wired. No other consumer repos (westside-app, pal-e-docs, pal-e-app, mcd-tracker-api, mcd-tracker-app, westside-contracts) have it yet.
  • Future scope: Issue #206 will roll this out to 8 repos. The fix must land before that rollout continues.
  • Rollback: Straightforward — revert the .woodpecker.yaml change in the affected repo(s).
  • Risk if buggy: Option A could deploy broken code if build passes but tests catch real bugs. Option B has no deploy risk (alerting only).

Decomposition Assessment

Apply three-thing limit and five-minute rule:
  • Option A: 2 file targets (template + basketball-api .woodpecker.yaml), 3 AC, under 5 min per repo. Template update = one PR in pal-e-platform. Consumer update = one PR in basketball-api. Two parallel agents, no sub-board needed.
  • Option B: 1-2 file targets in pal-e-platform (Prometheus alert rule + docs), 2 AC, under 5 min. Single agent pass.
No decomposition needed for either option. Fits within the three-thing limit and five-minute rule.

Recommendation

  • [SCOPE] Resolve Option A vs Option B before dispatch. This is a human design decision. Recommend Option A — unrelated test failures should not block valid deployments.
  • [LABEL] Fix story label: change story:PLAT-S2 to story:superuser-deploy on the board item.
  • [SCOPE] Create architecture note arch-woodpecker for the Woodpecker CI component in pal-e-docs.
  • [BODY] After decision: rewrite Acceptance Criteria as concrete testable statements (remove "Decision: Option A or Option B").
  • [BODY] Add File Targets section with specific paths: scripts/woodpecker-update-tag-step.yaml and (if Option A) consumer repo .woodpecker.yaml files.
  • [BODY] Add Test Expectations section with verification commands.
  • [BODY] Clarify Repo field based on decision — single-repo (Option B) or multi-repo (Option A).