Skip to content

Preview CRM Connections ​

Every PR preview opens with Salesforce (the foo9 dev org) and HubSpot (the "OnRamp CRM - Nonprod" portal) already connected through OnRamp's own CRM broker. No preview holds a Prismatic credential. When a preview's CRM is broken, the cause is almost always one of the shared pieces below, and fixing it fixes every preview at once.

Owner: PlatformUpdated: 2026-10-05

How a preview is connected ​

PieceWhereWhat it does
Preview Salesforce appExternal Client App "OnRamp Previews", local to foo9 (00DDo000001B9fNMAS)Its client-credentials flow, run as the user set on the app's policies, is the connection every preview starts with. Connect in a preview consents to it too. Only foo9 users can use it.
Preview HubSpot appPrivate app defined in infra/hubspot-preview-app/, allowlisted to portal 51740383One consented grant on it is the HubSpot connection every preview starts with. HubSpot refuses installs anywhere else.
Fleet secretsSSM /onramp/pr-previews/crm/*, written by the previews stack from infra/app/Pulumi.previews.yamlBoth apps' secrets and the shared HubSpot grant. Only a preview broker's role reads them; anyone who can push a same-repo branch can read them through the preview deploy role, which is why each reaches only the test org and portal.
Shared connectioncrm-broker/src/crm_broker/shared_connection.pyOn a read for vendor 0 whose row holds no credential, the broker copies the shared connection in, checking it reaches the pinned org or portal.
Preview database stepdevtools/db/preview-crm-fixture.ts, run after migrateTurns the seed's two connections into OnRamp-owned ones, deletes their Prismatic flow rows and credentials, and turns both self-refresh gates on.
Callback relayhttps://crm-oauth.preview.onrampapps.com/callback, in infra/app/cf-fn-api-dispatch.jsThe one callback both apps register. It redirects to the preview the connect state names, and nowhere else.

Disconnect and Connect in a preview ​

  • Disconnect removes the connection and makes the broker forget its copy. The shared connection is never ended at the CRM; a grant the preview minted itself through Connect is revoked at Salesforce.
  • Connect consents through the relay. For Salesforce choose My Domain foo9-dev-ed.develop.my.salesforce.com; for HubSpot, portal 51740383.
  • Salesforce forces refresh-token rotation and a 30-day idle expiry on the preview app, so a grant minted in a preview is only ever refreshed by that preview. Salesforce also keeps five approvals per user per app: a foo9 user's sixth Connect across previews retires their oldest preview-minted grant.
  • A DB refresh restores the seeded connections; a later read copies the shared connection back in.

When it breaks ​

SymptomCauseFix
Broker error naming a connection that "reaches X, not the pinned Y"The fleet's grant or app points at another org or portalRe-mint on the pinned one (below). Never repoint the pin.
Salesforce reads fail with invalid_client, or invalid_grant on the client-credentials flowThe app's secret changed, or its client-credentials flow or run-as user was switched offFix the app in foo9 Setup, then reset its secret (below)
HubSpot reads fail with BAD_REFRESH_TOKENThe shared grant was revoked or the app uninstalled from the portalRe-mint the HubSpot grant (below)
Connect lands on a CRM error page about the redirect URIThe relay URL is missing from that app's callbacksAdd https://crm-oauth.preview.onrampapps.com/callback back

Re-mint the shared HubSpot grant (opens HubSpot's consent page; choose portal 51740383):

bash
AWS_PROFILE=admin bun run crm.preview-fixture-grant

Reset an app secret (prompts for the value; keys are crmPreviewSalesforceClientSecret and crmPreviewHubspotClientSecret):

bash
cd infra/app && AWS_PROFILE=nonprod-admin PULUMI_BACKEND_URL=s3://onramp-pulumi-state-375255020707 pulumi config set --secret crmPreviewSalesforceClientSecret --stack organization/app/previews

Commit infra/app/Pulumi.previews.yaml; the previews stack applies it to SSM when it lands on main.

What previews cover, and what they don't ​

Previews review workflow creation against a live CRM: the trigger step's object, field and option pickers, saving, and publishing. Trigger events are deliberately out of scope: inbound delivery is not wired, so those paths fail fast rather than mutating CRM objects from an ephemeral environment.

The seed's two connections ​

The golden seed still carries vendor 0's Salesforce and HubSpot connections (or_integration 39 and 38) in the shape Prismatic instances gave them, with their Prismatic flow rows. Those instances were deleted with the rest of OnRamp's US Prismatic customers on 2026-10-23 and cannot be revived. Nothing in a preview reads them: the database step converts both rows and deletes the flow rows after every migrate, and the reseed only checks that both rows still exist bound to the pinned org and portal (devtools/db/crm-fixtures.ts).

Looks like this, isn't this ​

A Salesforce publish can 400 with the connection perfectly healthy: provisioning a Flow needs Metadata API permissions on the user the preview app runs as. The nested Salesforce error never reaches the toast — read the Flask log. That is a foo9 permissions fix.

The "Deploy preview (pipeline)" job failing on execution reaches a terminal state / oversized event is parked in S3 is not this either — that fixture vendor is a separate, third connection behind the integrations-pipeline executor's pre-claim hydrate, not one of the two pinned here. See docs/runbooks/integrations-pipeline-shadow.md's "Known: the preview...smoke check has been red fleet-wide" callout.

Internal documentation — gated behind Cloudflare Access.