Integrations

Orbit lets a project connect third-party tools, along three separate axes: notify integrations (Discord today; Slack and others are shown in the catalog as "coming soon") push Orbit activity out via a webhook, import integrations (Jira today; Linear, Asana, Trello are catalog-only stubs) pull issues/epics/subtasks in from a remote system on request, and github — the one integration of this kind — links a pull request to an Orbit issue through a GitHub App installation. This category documents the whole system: the frontend catalog, the per-project settings persisted in the database, the event-driven pipeline that turns "something happened in Orbit" into "a message landed in Discord", the pull-based pipeline that turns "a user clicked Import" into "Jira's issues exist in Orbit", and the relay-based pipeline that links a GitHub pull request to an Orbit issue.

Guides, in the order you'd actually need them

1. Add a new integrationIntegrationsAdd a new integrationWorked example: turning Slack from a locked "coming soon" catalog card into a fully working integration, exactly the way Discord works today. Slack already… — turn a "coming soon" catalog entry (or a brand new one) into a real, working notify integration end to end.
2. Add integration settingsIntegrationsAdd integration settingsprojectintegrations currently stores, per project+integration pair: — give a notify integration its own config shape beyond "enabled" and a webhook URL (e.g. a channel name, an API key, a numeric option).
3. Add a new event typeIntegrationsAdd a new event typeWorked example: adding IssueCreated — a kind of activity that doesn't exist yet. Today, creating an issue only fires IssueAssigned, and only if it's create… — wire up an entirely new kind of activity (using IssueCreated as the worked example) so both user notifications and notify integrations can react to it.
4. Frontend ↔ backend wiring overviewIntegrationsFrontend ↔ backend wiring overviewA map of the whole feature, useful to read before diving into any of the other guides. Three separate flows: reading the settings page, writing a toggle/we… — the full request/response shape for the notify-integration feature, useful as a map before diving into guides 1–3.
5. Add an import integrationIntegrationsAdd an import integrationWorked example: turning Linear from a locked "coming soon" catalog card into a fully working import integration, the same way Jira works today. This is the… — turn a "coming soon" catalog entry into a real, working import integration (using Linear as the worked example, built from Jira's already-complete implementation).
6. The GitHub integrationIntegrationsThe GitHub integrationUnlike the notify (webhook) and import (pull) integrations covered in the other guides in this category, GitHub is a third kind: a GitHub App installation,… — how the actual, already-wired-up github-kind integration works: architecture (via the orbit-api relay), connecting a project, the <!-- orbit-issue:ID --> marker syntax, and troubleshooting.

Need to gate a new integration ability behind its own permission? See ../permissions/01-add-a-new-permission.mdRoles & permissions (RBAC)Add a new permissionThe general, step-by-step pattern for adding any new projects./issues./comments. permission and getting it to show up correctly in Settings → Roles & manag… in the roles & permissionsRoles & permissions (RBAC)Every project has its own role-based access control: four built-in system role tiers (Owner, Admin, Member, Viewer) plus any number of project-defined cust… category — that guide isn't repeated here since it applies to any projects.*/ issues.*/comments.* permission, not just integration ones.

The architecture in one paragraph

The frontend has a static catalog (resources/js/types/Integrations.ts) of every integration Orbit could ever support — name, icon, category, description, sub-options, and a kind: 'notify' | 'import' | 'github' discriminator — regardless of whether it's actually wired up yet (comingSoon: true/false). Per-project state (is it enabled, its webhook URL/credentials, which sub-options are on) lives in one database table, project_integrations. For notify integrations, domain events (App\Events\*) that already exist for in-app/email notifications — IssueAssigned, IssueUnassigned, IssueUpdated, CommentAdded — are also consumed by a second listener, NotifyProjectIntegrationsListener, which maps each event to a sub-option category (issue-activity / comment-activity) and hands it to whichever IntegrationNotifier the event's project has enabled for that category. For import integrations, there's no event to react to — a controller action dispatches a queued job that resolves an IntegrationImporter, maps the remote system's raw payload into a source-agnostic ExternalIssueDTO, and hands every DTO to the shared ImportOrchestratorService, which handles dedup (external_issue_links), field mapping (integration_field_mappings), and hierarchy (Issue::parent_id) the same way regardless of which remote system produced the DTO. The github kind is a third, self-contained shape: a GitHub App installation is proxied through the public orbit-api relay (see guide 06IntegrationsThe GitHub integrationUnlike the notify (webhook) and import (pull) integrations covered in the other guides in this category, GitHub is a third kind: a GitHub App installation,…) rather than a webhook or a pull-based import, so it gets its own settings panel (WorkspaceSettingsGithubConnectPanel) and its own scheduled poller (PollGithubRelayEvents) instead of reusing the notify/import pipelines. Adding an integration, a new kind of event, or a new importer never requires touching the other axes' plumbing — see the guides for exactly where each new piece plugs in.