Integrations API Rollout Runbook

Integrations API Rollout Runbook

Scope

This runbook covers rollout, verification, migration, and rollback for the monorepo-owned integrations surface:

• runtime: workers/consumer-api (/integrations/v1)
• contract: packages/api-contract
• control plane: apps/dashboard installation + credential flows
• docs: apps/docs
• verification lanes: tests/features/integrations-contract.mjs, tests/features/integrations-runtime.mjs, tests/features/integrations-resilience.mjs

External consumer repositories (WordPress, Drupal, SDKs) are downstream clients and are not deployed from this repository.

Rollout Steps

1. Update the canonical contract in packages/api-contract.
2. Implement matching runtime behavior in workers/consumer-api.
3. Update dashboard control-plane flows if the API change affects installations, credentials, origins, or audit visibility.
4. Regenerate integrations docs:
   • pnpm generate:api in apps/docs
5. Run the required validation:
   • pnpm test:integrations:contract
   • pnpm test:integrations:runtime
   • pnpm test:integrations:resilience
   • any package/app type-checks touched by the change
6. Deploy this monorepo’s runtime/docs changes.
7. Notify or coordinate with external consumer repositories only after the API contract and runtime are stable.

Required Verification

Minimum checks before rollout:

• /integrations/v1/health responds with the expected version
• /integrations/v1/installation still enforces installation auth correctly
• affected scoped endpoints return the documented shape or documented auth/scope errors
• docs and OpenAPI output match the shipped contract

Migration Guidance

When changing integrations behavior used by external consumers:

1. prefer additive changes over breaking changes
2. document any new scopes, fields, or error codes in the contract and docs
3. keep old behavior available during a short migration window when feasible
4. communicate required downstream updates to external consumer repositories
5. remove deprecated behavior only after downstream consumers have a clear migration path

Rollback Guidance

If rollout causes regressions:

1. stop promoting downstream consumer releases that depend on the new behavior
2. roll back the public API worker/docs deployment if backward compatibility was broken here
3. if the API is correct but the downstream client is not, roll back the external consumer repo instead
4. verify the old contract/runtime behavior with the integrations test lanes before resuming rollout

Prefer runtime rollback before making destructive dashboard or data-layer changes.

Coordination Notes

• This repository is the source of truth for the integrations contract and runtime.
• External consumer repositories must not rely on undocumented routes or internal schema details.
• Contract changes here should precede any downstream consumer implementation changes.