SchemaSync draft PRs

Turn hosted drift events into GitHub draft pull requests — with optional ToolChange manifest lint on the same branch.

Prerequisites: DriftGuard Pro or Team with schemasync_repo enabled, a GitHub App installation on your target repo, and OSS schemasync lint-nl for local NL contract checks.

What you will build

Install the DriftGuard SchemaSync GitHub App on a contracts repo.
Enable SchemaSync in the console Products panel.
POST drift webhooks to open draft PRs when breaking changes land.
Optionally attach ToolChange lint when toolchange_org is enabled.

Step 1 — GitHub App

Production uses the DriftGuard GitHub App. Set GitHub Actions secrets GH_APP_ID, GH_APP_PRIVATE_KEY (PEM), and GH_APP_SLUG — repo secret names cannot start with GITHUB_. Deploy syncs them to the Worker via scripts/sync-schemasync-secrets.sh. See Deploy for permissions and setup.

Install the App on the repo that should receive schema contract updates.

Record the installation ID from GitHub — you will pass it in webhook payloads as installationId.

GET /v1/schemasync/installations
Authorization: Bearer dg_…

Lists installations registered for your account after the first webhook upsert.

Step 2 — Enable SchemaSync

In Console → Products, toggle SchemaSync on a paid plan. Free plans cannot enable overlay products.

Step 3 — Drift webhook

When DriftGuard detects drift on a watched dependency, POST:

POST /v1/schemasync/webhook
Authorization: Bearer dg_…
Content-Type: application/json

{
  "watchId": "watch_…",
  "driftEventId": "evt_…",
  "installationId": "12345678",
  "repoFullName": "acme/api-contracts",
  "changes": [
    { "path": "paths./refund", "severity": "breaking", "message": "Required field added" }
  ]
}

When the GitHub App is configured, DriftGuard creates a real draft PR on a driftguard/schemasync/<event> branch with a changelog under .driftguard/schemasync/. Without app credentials (local dev), responses use deterministic stub PR numbers for integration tests.

Step 4 — ToolChange lint (optional)

When toolchange_org is enabled, draft PR detail includes a ToolChange lint comment on the branch. Disable ToolChange to open schema-only drafts.

Step 5 — Merge audit

After merging the draft PR in GitHub, record it for metering:

POST /v1/schemasync/draft-pr/merged
{ "draftPrId": "…" }

Local NL lint (OSS)

cd driftguard/packages/schemasync
pip install -e ".[dev]"
schemasync lint-nl --mode literal --synonyms schemasync.synonyms.yaml \
  --before baseline.yaml --after candidate.yaml

Common errors

Response	Meaning
`202 schemasync_disabled`	Enable SchemaSync in Products
`404 Drift event not found`	`driftEventId` must belong to `watchId`
`502 GitHub API`	Installation ID or repo permissions — check App install
`PRODUCT_REQUIRED: schemasync_repo`	Paid plan + product toggle required for merge endpoint