How to roll out integration changes to every customer

What matters here

• Test the new version as a customer, through the real setup screens, in a separate environment.
• Know before publishing whether the change needs the customer. A new connection or required setting always does.
• Give every new setting a default where you can. It turns a change that needs every customer into one that needs none.
• Release changes that need the customer in waves. A mistake should reach ten customers, not four hundred.
• Keep every version you publish, with what changed. Going back is only easy if you kept what you were going back to.

Who this is for

You own integrations that your product's customers run. Every change to one is a change for all of them, and some changes have broken customers who set up before them.

How it works in practice

From a change being ready to every customer running it.

1. 1

   The change is made in a development environment

   Never in production, where every customer's instance runs the same workflows.

2. 2

   It is tested as a customer

   An existing test instance updated, and a new one set up from scratch, through the real screens.

3. 3

   The change is sorted

   No change to connections or settings, or a new connection, permission or required setting the customer must supply.

4. 4

   The version is exported, kept and published

   Saved with what changed and whether it needs the customer, then published in production.

5. 5

   Changes that need nothing roll out on their own

   Every instance picks up the new version without the customer redoing setup.

6. 6

   Changes that need the customer go out in waves

   A first group asked to finish setup, then the rest once the first group is healthy.

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

1. 1

   Sort the change before you publish

   Know which kind you are shipping.

   Headless skills build-workflow

   Copy

   Use build-workflow. Compare the new version of the integration with
   the one in production and list every difference.
   
   For each one, say whether it needs anything from the customer:
   
     A new service to connect to
     A changed permission on an existing connection
     A new setting with no default, or a changed required setting
   
   If none of those, customers' instances update on their own. If any,
   every customer must upgrade, so tell me which differences could be
   given a default to avoid it.

2. 2

   Test as a customer, both ways

   The two paths customers take are both worth breaking.

   Copy

   In the development environment, update the existing test customer's
   instance to the new version and run it end to end. Then set up a new
   test instance from scratch through the same screens a customer uses.
   
   Check that the existing instance keeps its settings and its history,
   and that the new setup reads clearly to someone who has never seen it.
   
   Only export once both pass.

3. 3

   Keep every version

   Going back is only easy if you kept what you are going back to.

   Headless skills tray-gotchas

   Copy

   Use tray-gotchas. Export the project and keep the file in our
   repository, named by version, with a note: date, what changed,
   whether it needs the customer, and who approved it.
   
   Import into production and publish the new version of the solution.
   If the version adds or changes a connection, set up the production
   connection before publishing.

4. 4

   Release changes that need the customer in waves

   A mistake should reach ten customers, not all of them.

   Copy

   When the version needs customers to upgrade, pick a first wave: ten
   customers who use the integration actively and have a named contact,
   including at least one large account.
   
   Show them a prompt in our product to finish setup, with what is new
   and why. Watch their failure rate for two days.
   
   If it holds, show the prompt to everyone else, and remind customers
   who haven't upgraded weekly. Report daily: customers on each version,
   upgrades finished, and failures by version.

   Customers who never upgrade keep running the old version. Decide in advance how long you support it, and say so in the prompt.

What it connects to

The version lives in Tray. The prompt to upgrade lives in your product.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Questions people ask

Related guides