Flexport Production Readiness Gate
Overview
A checklist item passes only with a receipt tied to the immutable release and configuration. Read access, bookings, trade records, and webhook processing have different risk boundaries and must be approved separately.
Prerequisites
- Immutable release SHA and environment manifest
- Named technical, security/data, and business approvers
- Read-only canary, reconciliation plan, incident owner, and rollback
Instructions
Step 1: Gate identity and auth
Verify account, credential alias/type, endpoint resources, token caching, secret injection, revocation, and MCP role permissions where used.
Step 2: Gate contracts
Confirm v3/account version behavior, tolerant additive-field parsing, documented endpoints/tools, error classification, and pagination.
Step 3: Gate data
Approve field minimization, destinations, telemetry redaction, retention/deletion, and tenant boundaries.
Step 4: Gate mutations
Require durable operation keys, business approval for bookings/writes, ambiguous-outcome reconciliation, and one authoritative writer.
Step 5: Gate webhooks
Prove raw-body X-Hub-Signature-256 validation, durable enqueue before 200, deduplication, event allowlist, and gap reconciliation.
Step 6: Gate launch and rollback
Run a read-only canary, expand by cohort, test rollback, and attach all receipts to the release decision.
Authentication
REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.
Tool Discipline
Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.
Output
- Scoped decision or implementation artifact
- Redacted operation and validation receipt
- Failure, rollback, and follow-up ownership record
Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:
surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
release_sha: recorded-out-of-band
provider_reference: redacted
rollback_owner: logistics-platform
Examples
The launch record enables shipment reads and signed webhook ingestion but leaves booking disabled because its human approval and ambiguous-outcome reconciliation evidence is incomplete.
Error Handling
| Failure | Response | | --- | --- | | Evidence belongs to another SHA | Re-run the gate on the release candidate. | | Owner or rollback absent | Do not launch. | | Broad API key lacks exception | Replace it or obtain explicit risk acceptance. | | Mutation reconciliation unproven | Keep that capability disabled. |