Fork-Safe Flexport Contract CI

Overview

The required CI lane must run without Flexport secrets and remain safe for forks. Live verification belongs in a protected, non-fork, read-only lane with explicit environment approval.

Prerequisites

• Sanitized REST, MCP, OAuth-error, and webhook fixtures
• CI permissions model and fork-event policy
• Optional test credential approved through Flexport/account ownership

Instructions

Step 1: Build the required lane

Validate schemas, tolerant additive fields, pagination, error classification, webhook raw-body signatures, and mutation guards entirely from fixtures.

Step 2: Test secret absence

Assert default tests cannot resolve Flexport credentials or reach live mutation adapters.

Step 3: Protect fork execution

Never expose repository/environment secrets to untrusted pull-request code; keep required fork checks credential-free.

Step 4: Define an optional live lane

Run only from trusted refs after environment approval, inject a scoped credential, and permit one documented read-only proof.

Step 5: Block mutations

Enforce an adapter-level CI policy that rejects booking, document, invoice, or purchase-order writes even when a credential exists.

Step 6: Publish receipts

Attach test counts, fixture/source dates, release SHA, and redacted live outcome; never upload tokens or provider payloads.

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

Every pull request tests v3 shipment envelopes, MCP cursor handling, malformed webhook signatures, and ambiguous booking guards. A protected main-branch job may perform one shipment list read with a test credential.

Error Handling

Failure	Response
Fork can read a secret	Disable the lane and repair event/environment permissions immediately.
Fixture contains production data	Replace and purge it before rerunning.
Live job can mutate	Fail the policy gate and remove write-capable paths.
Schema drift appears	Update from current first-party docs and add a regression fixture.

Resources

• First-party source notes
• Flexport v3 API reference
• MCP tools
• Webhook endpoints