60 lines
1.5 KiB
Markdown
60 lines
1.5 KiB
Markdown
|
---
|
||
|
|
kind: task
|
||
|
|
slug: forge-webhook-receiver
|
||
|
|
title: Forge webhook receiver — PR and CI events
|
||
|
|
plan_slug: automation-foundation
|
||
|
|
epic_slug: forge-webhooks
|
||
|
|
status: ready
|
||
|
|
priority: P2
|
||
|
|
tenant_id: global
|
||
|
|
owner: unassigned
|
||
|
|
cursor_todo_id: null
|
||
|
|
updated_at: "2026-08-03"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Task summary
|
||
|
|
|
||
|
|
`POST /api/webhooks/forge/:repoLinkId` with HMAC signature verification; map forge events to `transition_convoy_status(actor: automation)`.
|
||
|
|
|
||
|
|
## Description
|
||
|
|
|
||
|
|
Core Epic 8 scope. Link PRs to convoys via branch naming convention (`convoy/<slug>/brief-N`) or PR body marker (`echodo-convoy: <uuid>`).
|
||
|
|
|
||
|
|
### Events (minimum)
|
||
|
|
|
||
|
|
| Forge event | Convoy transition |
|
||
|
|
|-------------|-------------------|
|
||
|
|
| PR opened | Ensure convoy in `pr_review` (if Gate 2 not yet human-approved, notify only) |
|
||
|
|
| PR merged | `pr_review` → `merged` when Gate 2 already approved |
|
||
|
|
| CI completed (failure) | Optional `blocked` or `convoy_events` notify |
|
||
|
|
|
||
|
|
### Security
|
||
|
|
|
||
|
|
- Per-repo webhook secret in `repo_links` metadata (reference env var name, not value)
|
||
|
|
- Zod-validated payload per `forge_type`
|
||
|
|
|
||
|
|
## Dependencies
|
||
|
|
|
||
|
|
- Epic 3, 4, 7
|
||
|
|
|
||
|
|
## Subtasks
|
||
|
|
|
||
|
|
- [ ] Route handler + signature verification
|
||
|
|
- [ ] GitHub + Forgejo payload parsers
|
||
|
|
- [ ] Convoy lookup by branch/body marker
|
||
|
|
- [ ] Register webhook URL helper on connect (optional UX)
|
||
|
|
|
||
|
|
## Estimation
|
||
|
|
|
||
|
|
M
|
||
|
|
|
||
|
|
## Acceptance criteria
|
||
|
|
|
||
|
|
- [ ] Merge webhook moves convoy from `pr_review` to `merged` when Gate 2 approved
|
||
|
|
- [ ] Invalid signature returns 401
|
||
|
|
- [ ] Unknown branch logs and returns 200 (no retry storm)
|
||
|
|
|
||
|
|
## Links
|
||
|
|
|
||
|
|
- Epic: `./Epic-forge-webhooks.md`
|