pal-e-docs

Review: Bug: Woodpecker webhook not firing on Forgejo squash merge

review-273-2026-04-07 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Checked against template-issue-bug (Bug template):
  • [x] Type -- Bug
  • [x] Lineage -- Standalone, discovered during CRM incident response 2026-04-07
  • [x] Repo -- forgejo_admin/pal-e-platform
  • [x] What Broke -- Squash merge on basketball-api #382 did not fire Woodpecker webhook; no pipeline created for merge commit 801bc43
  • [x] Repro Steps -- 4 steps provided, clear and reproducible
  • [x] Expected Behavior -- Every squash merge to main triggers a Woodpecker push pipeline
  • [x] Environment -- prod / woodpecker + forgejo namespaces, 4 idle workers, commit SHA provided
  • [x] Acceptance Criteria -- 4 criteria provided
  • [x] Related -- project and affected repo referenced
  • [ ] File Targets -- Not present. Acceptable for investigation-first bug where root cause is unknown.

Traceability

  • [ ] story:PLAT-S2 -- NOT FOUND in project-pal-e-platform user-stories section. The registered stories are: superuser-deploy, superuser-observe, superuser-recover, superuser-onboard-service, superuser-remote-access. PLAT-S2 does not match any. [LABEL] Replace story:PLAT-S2 with story:superuser-deploy (CI pipeline reliability maps to the deploy story).
  • [ ] arch:woodpecker -- arch note MISSING. No arch-woodpecker note found in pal-e-docs. [SCOPE] Create architecture note arch-woodpecker for Woodpecker CI component.
  • [ ] arch:forgejo -- arch note MISSING. No arch-forgejo note found in pal-e-docs. [SCOPE] Create architecture note arch-forgejo for Forgejo component.
  • [x] Forgejo issue -- #273, open, valid URL

File Targets

No file targets listed in the issue. This is acceptable for a bug where root cause is unknown and investigation is the first AC. Likely targets after investigation:
  • Woodpecker Helm values (webhook receiver config)
  • Forgejo webhook settings (admin UI or Terraform-managed)
  • Woodpecker server logs for webhook receipt
Relevant context files in pal-e-platform:
  • /home/ldraney/pal-e-platform/.woodpecker.yaml -- Woodpecker pipeline config
  • /home/ldraney/pal-e-platform/scripts/woodpecker-update-tag-step.yaml -- kustomize tag update step

Repo Placement

Correct. Filed on pal-e-platform which owns Woodpecker and Forgejo infrastructure via Terraform/Helm. The symptom manifested on basketball-api but the root cause is in platform webhook/CI config. No multi-repo issues needed -- the fix will be in platform config.

Dependencies

  • Board item #703 (issue #254) -- Woodpecker pipeline restart skips deploy steps (arch:woodpecker, backlog). Related but distinct: event:push metadata loss on restart vs webhook not firing at all.
  • Board item #728 (issue #259) -- Woodpecker push-to-main pipelines fail with queue/ack errors (backlog). Potentially same root cause cluster -- server-side queue issues could explain missed webhooks.
  • Board item #882 (issue #274) -- update-kustomize-tag skipped when CI tests fail (backlog). Companion bug from the same incident. Different symptom, same incident timeline.
Dependencies not documented in the issue body. [BODY] Add cross-references to #254, #259, and #274 in the Related section.

Acceptance Criteria

4 criteria, assessment:
  • "Root cause identified" -- Investigative, verifiable by documentation. Good.
  • "Verify webhook delivery logs in Forgejo admin" -- Specific action, testable via Forgejo admin UI. Good.
  • "Fix applied so squash merges reliably trigger pipelines" -- Functional test by squash-merging a test PR. Good.
  • "Workaround documented if this is a known issue" -- Documentation deliverable. Good.
Missing coverage: no AC for verifying the fix works across all repos, not just basketball-api. If the root cause is repo-specific webhook config, other repos may have the same gap. [BODY] Add AC: "Verify webhook config is consistent across all repos with Woodpecker pipelines."

Blast Radius

HIGH. If squash merges silently skip webhooks, any repo using squash merge will have missed deployments. This affects all 8+ repos with Woodpecker CI pipelines. The incident already blocked deployment of two critical bug fixes (#377 photo placeholder, #378 teams 422). Three related Woodpecker bugs on the board (#254, #259, #274) suggest a pattern of CI reliability problems. Rollback is straightforward if the fix is config-only (Helm values or Forgejo webhook settings).

Decomposition Assessment

Single investigation bug. 0 explicit file targets (investigation first), 4 acceptance criteria, estimated single agent pass under 5 minutes for the investigation phase. No decomposition needed. If the fix turns out to span multiple components (e.g., Forgejo webhook config + Woodpecker Helm values + cross-repo audit), decomposition should be revisited at that point.

Recommendation

  • [LABEL] Replace story:PLAT-S2 with story:superuser-deploy on board item #881 -- PLAT-S2 is not a registered user story in project-pal-e-platform.
  • [SCOPE] Create architecture note arch-woodpecker for Woodpecker CI component.
  • [SCOPE] Create architecture note arch-forgejo for Forgejo component.
  • [BODY] Add cross-references to related issues #254, #259, #274 in the Related section of issue #273.
  • [BODY] Add AC: "Verify webhook config is consistent across all repos with Woodpecker pipelines."
  • [LABEL] Set board item #881 title (currently null) to match the Forgejo issue title.