nomadcode/agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/gito-http-webhook-consumer-readiness.md

Milestone: Gito HTTP Webhook Consumer Readiness

위치

• Roadmap: agent-roadmap/ROADMAP.md
• Phase: agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md

목표

NomadCode Core의 Gito branch event consumer를 Gito 제공 계약 gito.forgejo-branch-events.v1의 signed HTTP webhook delivery와 맞춘다. Gito는 외부/인접 consumer에게 /proto-socket binary transport를 요구하지 않으며, NomadCode는 branch.updated JSON delivery를 wakeup signal로 받아 target branch revision을 재검증한 뒤 기존 creation sync enqueue 흐름으로 수렴한다.

상태

[완료]

승격 조건

• 없음

구현 잠금

• 상태: 해제
• SDD: 필요
• SDD 문서: agent-roadmap/sdd/agent-ops-mcp-control-plane/gito-http-webhook-consumer-readiness/SDD.md
• 잠금 해제 조건:
  • SDD 잠금이 해제되어 있다
  • SDD 사용자 리뷰가 없거나 승인/해결되었다
  • Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  • Evidence Map이 plan의 Spec Targets와 완료 시 Spec Completion으로 검증 가능하게 연결되어 있다
  • Workspace lock nomadcode:gito-http-webhook-consumer-readiness의 모든 rely-on.status가 enable이다
• 결정 필요: 없음

범위

• Gito -> NomadCode signed HTTP webhook callback endpoint
• X-Gito-Event, X-Gito-Delivery, X-Gito-Signature 기준의 delivery 검증과 idempotency 경계
• Gito branch.updated base payload를 NomadCode 전용 필수 필드 없이 소비하는 schema boundary
• 기존 gitoevents decode/filter와 gitosync branch scan/enqueue 의미 로직의 HTTP transport 재연결
• Gito webhook subscription bootstrap과 NomadCode callback/secret 설정 문서화
• invalid signature, malformed payload, duplicate delivery, not-ready revision, Gito retry에 대한 운영 로그와 실패 처리

기능

Epic: [webhook-consumer] Gito HTTP webhook intake

NomadCode Core가 Gito branch event delivery를 외부 HTTP callback으로 받고, Gito 원문 계약을 source of truth로 소비한다.

• [receiver] Gito branch.updated HTTP callback endpoint를 추가한다. 검증: signed branch.updated delivery는 수락되고, wrong event와 invalid signature는 side effect 없이 거부된다.
• [payload-boundary] Gito base payload를 repo/branch/revision/change hint 중심으로 해석하고 NomadCode 전용 필드를 요구하지 않는다. 검증: NomadCode 전용 필드 없이도 on-target event가 decode된다.
• [idempotency] X-Gito-Delivery와 revision key 기준으로 duplicate delivery를 중복 enqueue 없이 처리한다. 검증: 같은 delivery 또는 같은 revision 재전달이 정확히 한 번의 sync 후보로 수렴한다.

Epic: [sync-bridge] Revision verification and creation sync

HTTP webhook wakeup을 기존 branch revision 재검증과 creation sync enqueue 의미 로직으로 연결한다.

• [scan-enqueue] HTTP receiver에서 받은 on-target event가 target branch fetch/scan 이후 EnqueueRoadmapCreationSync로 이어진다. 검증: 한 건의 Gito webhook delivery가 target branch 재검증 후 정확히 하나의 creation sync job으로 수렴한다.
• [config-docs] GITO_PROTO_SOCKET_URL 중심의 소비자 설정을 webhook callback endpoint, signing secret, Gito subscription bootstrap 기준으로 교체한다. 검증: secret 원문 없이 local/dev webhook consumer 설정 경로가 문서화된다.
• [failure-ops] invalid signature, malformed payload, not-ready revision, duplicate delivery, Gito retry가 core server shutdown이나 중복 Plane mutation으로 이어지지 않는다. 검증: 장애 입력이 안전하게 reject/drop/retry 후보로 기록된다.

완료 리뷰

• 상태: 통과
• 요청일: 2026-06-19
• 완료 근거:
  • scan-enqueue가 agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/complete.log의 Roadmap Completion과 Spec Completion(S04) PASS 근거로 완료되었다.
  • 모든 기능 Task가 체크되었고 SDD는 [승인됨]/잠금 해제, workspace lock은 agent-ops/bin/roadmap-dependency-checker.sh 결과 true로 확인했다.
  • 코드 레벨 종료 감사에서 Gito 제공 계약에 맞춰 X-Gito-Delivery 누락 delivery를 side effect 없이 400으로 거부하도록 보강했고, 관련 테스트를 갱신했다.
  • 최종 검증은 cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync ./internal/config, cd services/core && go test -count=1 ./..., git diff --check PASS로 확인했다.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 코드 레벨 종료 감사와 소규모 계약 보강 후 완료/archive 대상으로 확정했다.

범위 제외

• Gito Forgejo webhook producer와 outbound webhook delivery worker 구현
• Gito 제공 계약 gito.forgejo-branch-events.v1 원문 변경
• Gito event schema를 NomadCode 전용 필드로 확장하는 작업
• Plane Todo -> In Progress 실행 lifecycle
• Milestone Task와 Plane 하위 티켓 동기화
• Flutter UI에서 branch event 상태를 표시하는 기능

작업 컨텍스트

• 관련 경로: services/core/internal/gitoevents/, services/core/internal/gitosync/, services/core/internal/http/, services/core/cmd/server/main.go, services/core/internal/config/, services/core/docker-compose.yml, README.md, packages/contracts/notes/flutter-core-api-candidates.md
• 외부 계약: Gito agent-contract/provided/gito-forgejo-branch-events-v1.md (gito.forgejo-branch-events.v1)
• 관련 Gito Milestone: Forgejo Branch Event MVP, Webhook Revision Reconcile
• 표준선(선택): NomadCode는 Gito branch.updated delivery를 wakeup signal로만 사용하고, 최종 판단은 target branch fetch/scan과 provider identity 재검증으로 수행한다. Gito schema는 여러 consumer를 위한 범용 규약이며, Gito -> external consumer delivery는 HTTP webhook/callback이고 /proto-socket은 Gito 내부 control/runtime transport로 본다.
• 이전 방향 정리: Gito Proto-Socket Consumer Wire Readiness는 archive된 완료 기록으로 보존하되, 현재 프로젝트 방향에서는 NomadCode/Gito 외부 소비 표면으로 재사용하지 않는다.
• 우선순위: 최우선 - Roadmap Driven Agent-Ops Automation과 Milestone Execution Lifecycle Sync보다 먼저 SDD gate와 Gito 외부 의존 잠금 상태를 정리한다.
• 선행 작업: Gito 제공 계약 gito.forgejo-branch-events.v1의 HTTP webhook delivery 경계 확인
• 외부 의존 잠금: Gito agent-roadmap/phase/provider-change-request-integration/milestones/webhook-revision-reconcile.md의 consumer webhook subscription과 signed HTTP delivery 구현이 완료되어야 실제 연동 구현/검증을 닫을 수 있다.
• 후속 작업: Milestone Execution Lifecycle Sync
• 확인 필요:
  • SDD 작성과 gate 확인 후 구현 잠금을 해제한다.