feat: implement deployment sync module with Supabase persistence and …

[TechBroAfrica]

closes #544

PR: feat/be-branch-metadata-sync - Ingest and Sync GitHub Branch/PR Deployment Metadata
Description
This PR implements the backend database schema, ingestion webhook, and admin endpoints required to sync branch and PR deployment metadata. This enables operators to inspect preview deployments and contributor environments in a single location.

Key Changes
Database Migration: Added the migration script 20260627000000_create_branch_deployments_table.sql to define the public.branch_deployments table and create an index on pr_number.
Webhook Ingestion (POST /deployment-sync/webhook): Exposes a public endpoint to receive branch name, PR number, commit SHA, preview URL, status, and event timestamp.
Idempotency & Replays: The endpoint is safe to replay and handles duplicate deliveries.
Stale Updates: Compares incoming eventTimestamp with the stored database value, discarding updates that arrive out of order (stale updates).
Admin Queries:
GET /admin/deployments/branch/:branchName: Returns the deployment status for a given branch name.
GET /admin/deployments/pr/:prNumber: Returns an array of deployment histories for the specified PR number.
Both routes are guarded by ApiKeyGuard and require the admin scope.
Testing: Integrated full unit tests covering duplicate delivery, stale update checks, and database failure branches.
Verification Plan

1. Automated Tests
   Ensure the new unit test suites pass successfully:

bash
npm run test:unit src/deployment-sync/tests/deployment-sync.service.unit.spec.ts
npm run test:unit src/deployment-sync/tests/deployment-sync.controller.unit.spec.ts
2. Manual Verification
You can test the endpoints locally using curl:

Ingest metadata:

bash
curl -X POST http://localhost:4000/deployment-sync/webhook
-H "Content-Type: application/json"
-d '{
"branchName": "feat/be-branch-metadata-sync",
"prNumber": 60,
"commitSha": "abc123commitsha",
"previewUrl": "https://quickex-preview-pr-60.vercel.app",
"status": "success",
"eventTimestamp": "2026-06-27T08:00:00.000Z"
}'
Verify stale check:

bash
curl -X POST http://localhost:4000/deployment-sync/webhook
-H "Content-Type: application/json"
-d '{
"branchName": "feat/be-branch-metadata-sync",
"prNumber": 60,
"commitSha": "stale-commit-sha",
"previewUrl": "https://quickex-preview-pr-60.vercel.app",
"status": "failed",
"eventTimestamp": "2026-06-27T07:30:00.000Z"
}'
Verify that the response returns the original data from 2026-06-27T08:00:00.000Z and does not overwrite it.

Admin Query by Branch:

bash
curl -X GET http://localhost:4000/admin/deployments/branch/feat/be-branch-metadata-sync
-H "Authorization: Bearer <ADMIN_API_KEY>"

[drips-wave]

@TechBroAfrica Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Cedarich]

@TechBroAfrica fix workflow