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

In Console → GitHub, enable SchemaSync under Products first. When the hosted GitHub App is provisioned, click Install GitHub App and choose your contracts repo. If the button is unavailable, your DriftGuard operator must create the GitHub App and set Worker secrets — use Link installation with the numeric installation ID from GitHub → Settings → Applications.

The App needs repository contents and pull requests (read/write). Configure the App webhook to POST /v1/schemasync/github/webhook with Pull request events so merged remediation PRs auto-resolve incidents (no manual merge callback).

Setup URL for OAuth install return: https://driftguard.org/api/account/schemasync/github/callback

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

Lists installations registered for your account after install or 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

When the GitHub App webhook is configured, merging the draft PR on GitHub auto-records merge, resolves incidents, and unblocks agents. You can also record manually:

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