Sharing Integrations
A project can share one of its integrations with other projects in your organization. Each project that wants it imports it, and its agents can then use it with the sharing project's connection and credentials. Nothing changes in a project until one of its admins imports the integration.
Use sharing when several teams use the same system, such as one GitHub organization or one Grafana. A GitHub organization can be connected only once, so sharing is how other projects use it.
Words used here
- Owning project: the project the integration belongs to. It keeps the connection, the credentials, and the right to delete the integration.
- Receiving project: a project the integration is shared with.
- Import: what a receiving project's admin does to take a shared integration into the project. The project gets its own copy, shown as Imported.
Share an integration
- In the owning project, open Settings → Integrations, open the integration, and choose the Sharing tab. Every integration has one. It lists the project's connections of that type, or, until one is shared, shows how sharing works.
- Choose Share on the connection's row, or Share integration connection when none is shared yet.
- Choose who can import it:
- All projects, the default: every project in your organization, including projects created later.
- Specific projects: tick each project that needs it. As in the project picker, Recent, Starred and All list the projects, and the search finds any project by name or ID. The box above the list ticks every project shown. You can only pick projects you can see.
- Choose Share. The dialog then lists the new projects you are an admin of. Import imports it into that project on the spot, under the name described in Import a shared integration, and marks it Imported. Admins of the other projects import it from their Shared resources.
You can also share from Settings → Shared resources → Shared by this project → Share resources: choose Integrations, then the connection, and Next to choose the projects. Pick several, of any type, to share them with the same projects at once; each keeps who it is already shared with.
To change who it is shared with, open its sharing page and choose Edit sharing. A save sends only what you added and removed, so two admins changing it at the same time keep each other's changes. Projects you can't see that were already selected stay selected.
Sharing with specific projects emails each project's admins. Sharing with all projects doesn't; each project sees the integration as Available.
See what is shared
Settings → Shared resources has two tabs, each one list of integrations, agents and skills. The Type filter narrows it to one kind.
- Imported from other projects: what the project imported first, then what it can import, marked Available.
- Shared by this project: each integration the project shares, who it is shared with, how many projects imported it, and when it was first shared.
Agents and skills are shared the same way: see Sharing Agents and Skills.
Choose a connection on either the integration's Sharing tab or Shared by this project to open its sharing page. It lists the projects it is shared with and which of them imported it. Projects you can't see appear only as a count.
Import a shared integration
- In the receiving project, open Settings → Shared resources → Imported from other projects.
- Choose Import on the integration's row, marked Available.
- Keep the proposed name or type another. Names are unique in a project, so when the project already has one with the same name, the proposal adds the owning project's ID, for example
github-platform. - Choose Import. The imported integration opens on its Configure tab.
From then on, agents in the project can use it, and it appears among the project's integrations, labelled with the project it comes from.
If the project has two integrations of the same type, for example its own GitHub and an imported one, agents choose one by name on every call, and triggers match on the name. Rename the imported integration before you set up triggers if you want a different name.
Connect an account another project already connected
A GitHub organization, Microsoft Teams tenant, PostHog organization or Zoom account connects to Autoheal once. To use it in a second project, share and import it; don't connect it again.
The connect page for these integrations lists Shared with this project at the top when other projects share connections of that type. Choose Import there.
If other projects already connected an account of this kind, Install asks first. It lists each one with the project that connected it. Choose Import on one shared with your project. One that isn't shared says so: a Project Admin of that project can choose Share right there; anyone else asks one of them. Choose Continue to connect a different account. Connections made with a token, such as a GitHub personal access token, appear only in the list.
If you connect the account anyway:
- Your project already has it, as its own or as an import: Autoheal opens that connection and says it was already there. Nothing new is created.
- Another project has it and shares it with yours: you return to the connect page with a message that names that project. Import the connection from Shared with this project.
- Another project has it and doesn't share it: the message names that project. Ask one of its Project Admins to share the connection with your project, then import it.
The message stays until you close it.
On GitHub, an organization that already has the Autoheal app shows Configure instead of Install. Configure only changes that installation; it doesn't connect the organization to your project. If you save a change there, Autoheal says nothing new was connected.
What a receiving project can change
| Owning project | Receiving project | |
|---|---|---|
| Connection settings and credentials | Changes them; changes apply to every imported copy at once | Read-only |
| Turning it on or off | Turns it on or off for every project | Read-only |
| Name, description and labels | Its own | Its own |
| Webhook URL and signing secret | Its own | Its own |
| Sharing it with other projects | Yes | No |
| Deleting it | Deletes its integration | Deletes its imported copy only |
Webhooks
Each imported copy has its own webhook URL and signing secret, shown on its Configure tab. Events sent to a project's URL land in that project and fire that project's triggers. The owning project's URL doesn't change.
To send different alerts to different projects, add one destination per project in the source system and route each project's alerts to it. For example: a Grafana contact point with a notification policy, an Alertmanager receiver, a Jira webhook with a JQL filter, or a webhook on each GitHub repository. A GitHub organization-wide webhook sends every repository's events to one URL, so use repository webhooks instead.
Catalog syncs
An imported integration syncs into the receiving project, the same as the project's own integrations:
- Repositories: every repository the integration reaches is added to the project's catalog, and its sandboxes can clone them.
- PagerDuty: services, teams and people go into the catalog, and schedules and escalation policies into On-Call.
- ServiceNow and Import from integration: land in the project that runs them.
Each project keeps its own copy of what it syncs.
Stop sharing
On the connection's sharing page, choose Stop sharing, then confirm. The dialog lists the projects that imported it. To remove only some projects, use Edit sharing. In each project that imported it and is no longer included:
- its copy shows No longer shared or deleted in Shared resources, and its admins get an email;
- its tools and webhook stop, and it can no longer use the owning project's connection or credentials;
- the repositories it synced are removed; other synced records, such as On-Call schedules, stay.
Sharing again doesn't bring a copy back. The project's admin deletes the copy and imports the integration again.
Delete a shared integration
When the owning project deletes an integration that other projects imported, their copies are not deleted. Each copy shows No longer shared or deleted in Shared resources, stops working, and can't be turned on again, because the credentials were deleted. The Delete dialog lists the projects that imported it, and their admins get an email.
A receiving project deletes its copy with Delete, as for any of its integrations. The owning project's integration doesn't change, and the project can import it again while it is still shared.
What a copy shows once it stops
Whether its owner stopped sharing it or deleted it, the receiving project is told the same, on the copy's page, in Shared resources and in the email to its admins. The copy's page says the integration is either no longer shared or deleted, and to reach out to the owning project's admin or delete it. It shows none of the connection settings it used. Its name, description, labels and webhook URL (turned off) stay until that project's admin deletes it with Delete.
Who can do what
| Action | Permission | Checked on |
|---|---|---|
| Share, change who it is shared with, stop sharing | sharing:update | The owning project |
| See an integration's sharing, and the Shared resources page | integration:read | The project shown |
| Import | integration:create | The receiving project |
| Delete an imported copy | integration:delete | The receiving project |
Only Project Admins hold sharing:update, integration:create and integration:delete. Org Admins don't share a project's integrations unless they are also that project's Project Admin. See Roles & Permissions.
Every share, stop, import and delete of an imported copy is recorded in the access log (share, unshare, link and unlink), with the integration and the project concerned. Read it through the API, GET /api/v1/rbac/audit-events, with audit:read on the organization (see Managing Access).
Things to know
- Every receiving project uses the owning project's credentials, so they share the source system's rate limits.
- A receiving project's sandboxes clone repositories with a code repository integration's token, so code running there can read the token. Share one only with projects you'd trust with it.
- If the owning project's credentials stop working, every imported copy stops too. Only the owning project gets the failure email.
- Each project's copy of a PagerDuty schedule has its own handoff notices. If two projects turn them on for the same schedule, the person on call gets each notice twice.