Last updated February 18, 2025

In this guide, we will take you step by step through the process of making your existing Heroku Add-on “Shareable.”

Your staging add-on

If you have a staging environment and corresponding Heroku Add-on that differ from your publicly-available Heroku add-on, we highly recommend testing these changes extensively there before promoting these changes to your main offering.

Supporting multi-app attachment

To make an add-on shareable between apps, add the attachable flag to the requires array in your manifest. No further changes should be necessary for this feature.

Supporting multiple installs per app

To allow an add-on service to be installable to the same application multiple times:

1. Add the many_per_app flag to the requires array in your manifest.
2. Be sure to remove any uniqueness constraint on the heroku_id field in provision requests.
3. Use the new provision-time uuid field for Heroku-side uniqueness, if desired
   • This field will only be present for add-ons flagged into the new runtime or for provisions from users or applications that are flagged in.
4. Return your own provision response id that is unique per installation, not app (i.e. not a derivative of heroku_id like app123@heroku.com)
5. Optionally back-fill the uuid field from the [Add-on Partner API][add-on-partner-api-reference] as needed. The field may be null for some installations, until migration and roll-out is complete.

When the many_per_app flag is enabled, users will be able to override the “attachment name” which is used as the prefix to env vars.

For an add-on named foo-bar which sets FOO_BAR_A and FOO_BAR_B, we will treat this as setting A and B instead by stripping out a normalized variant of the add-on service slug from the beginning of the string. (In a future integration version, the service-prefix won’t be necessary but is necessary today for backwards compatibility)

• A and B are prefixed by the attachment name from the perspective of the application. For an attachment named BALLOON, this will result in BALLOON_A and BALLOON_B vars being exposed.
• Attachment names are chosen with the following heuristic
  1. Customer-provided name (e.g. WORKER; if conflict, error)
  2. Partner-recommended name (e.g. REDIS; if conflict, next)
  3. Normalized add-on service slug (e.g. REDISGREEN; if conflict, next)
  4. Normalized add-on service slug + random color (e.g. REDISGREEN_CYAN; if conflict, pick new random color; if color pool exhausted, error)
• Custom names may be allowed even without many_per_app enabled in the future.
• To provide a recommended attachment name return a root-level key named recommended_prefix in the provision response. Based on partner feedback, this recommendation may move to the manifest

What to test

Exercise every aspect of your add-on to be sure the above changes did not have a negative impact on functionality; also test the following behaviors specific to Heroku integration, where they apply to your add-on:

• Provisioning for the same app multiple times (if you chose to support many-per-app)
• Multiple attachments of one installation to the same app
• SSO in the context of multiple installations on a single app, and with attachments to multiple apps
• Custom attachment naming
• Updating configuration variables and checking that they propagate to all attached applications
• Plan upgrades and downgrades