> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace Gmail Migration Runbook (PF-101 T4.5)

> Migrate a tenant from the legacy Gmail platform secret to the PF-101 per-tenant Google Workspace connector: steps, gating smoke test, retirement.

**Audience:** Platform operators / on-call engineers.
**Scope:** Gmail sending only (WS4). Directory, Calendar, Licensing, and Reports onboard through the standard [Admin Setup](/integrations/GOOGLE_WORKSPACE_SETUP) flow.
**Related:** [Overview](/integrations/GOOGLE_WORKSPACE_OVERVIEW) · [Compliance](/integrations/GOOGLE_WORKSPACE_COMPLIANCE) · [Security Review](/integrations/GOOGLE_WORKSPACE_SECURITY_REVIEW)

## How sender resolution works during migration

The email adapter (`supabase/functions/_shared/email-provider.ts`) resolves Gmail
credentials **PF-101 first, legacy second**:

1. If the tenant has an active `pf_google_workspace_connections` row with the
   `gmail` capability enabled, the adapter uses the PF-76 vault credential
   referenced by that connection (`credential_vault_ref`) and enforces the
   PF-101 gates — sender-domain allowlist (connection `primary_domain`) and the
   fail-closed BAA gate for PHI-capable sends (`baa_attested_at IS NOT NULL`).
2. Otherwise it falls back to the platform-wide `GMAIL_SERVICE_ACCOUNT_JSON`
   edge-function secret (legacy path, shared across all tenants).

Because resolution is per-tenant, migration is incremental: tenants move one at
a time, and the legacy secret stays in place until **every** tenant has passed
its smoke test.

## Per-tenant migration steps

1. **Connect the tenant.** Follow [Admin Setup](/integrations/GOOGLE_WORKSPACE_SETUP)
   §1–2: service account with DWD, scopes authorized in the tenant's Admin
   Console, JSON key stored via the PF-76 vault (`pf_store_credential`) from
   Settings → Integrations → Google Workspace.
2. **Enable the `gmail` capability** on the connection. If the tenant sends
   PHI-capable mail, record the BAA attestation first — the gate is
   fail-closed and unattested PHI sends are rejected with a policy error.
3. **Verify sender identity.** The configured sender must match the
   connection's `primary_domain` (sender allowlist). Update the org's
   `gmail_sender_email` setting if it still points at the shared legacy sender.
4. **Run the connection test** (Settings → Integrations → Google Workspace →
   Test connection). The `gmail` capability must report healthy; a
   `pf_google_workspace_sync_runs` row records the result.
5. **Smoke test (gating).** Send a non-PHI test message through the platform
   (e.g. a password-reset or test notification to an operator mailbox) and
   confirm:
   * the message arrives from the tenant's domain sender;
   * a `pf_google_workspace_sync_runs` row with capability `gmail` and a
     redacted `correlation_id` was written;
   * edge-function logs show no `Gmail service account not configured` or
     scope errors (`supabase functions logs email-send`).
6. **Record completion.** Note the tenant + date in the cutover tracker before
   moving to the next tenant.

## Legacy secret retirement

Only after **all** tenants have an active PF-101 Gmail connection and a passed
smoke test:

1. Confirm no fallback hits remain: search edge logs for the legacy-path
   warning over a full business cycle (7 days minimum).
2. Remove the platform secret: `supabase secrets unset GMAIL_SERVICE_ACCOUNT_JSON`.
3. Revoke the legacy shared service account's DWD grant in the Google Admin
   Console and delete its key.
4. Update [EMAIL\_SMS\_SETUP](/integrations/EMAIL_SMS_SETUP) and
   [EDGE\_FUNCTIONS](/integrations/EDGE_FUNCTIONS) to drop the
   `GMAIL_SERVICE_ACCOUNT_JSON` instructions (they document the legacy path
   while it remains supported).

## Rollback

A tenant can be rolled back instantly by disabling the `gmail` capability on
its connection — the adapter falls back to the legacy secret (while it still
exists). Do not retire the legacy secret until the rollback window has closed
for every tenant.

## Current status

* Adapter precedence, BAA gate, and sender allowlist are implemented and
  contract-tested (WS4 T4.1–T4.4).
* Live per-tenant smoke tests are **pending the BAA staging tenant**
  (tracked in `GOOGLE_WORKSPACE_SECURITY_REVIEW.md` §8); no tenant has been
  migrated yet, and the legacy secret remains active.