Integrations on Local and in the cloud

Every integration Orchestra offers can run in one of two homes:

This laptop (Orchestra Local). You connect your own account. The token stays in your operating system’s keychain, and everything the integration reads is written to the store on your laptop. Nothing is stored on Orchestra’s cloud.
Orchestra’s cloud. Your workspace connects once (the Orchestra GitHub App, or a Linear workspace connection), and what it reads is stored in Orchestra’s hosted store, visible to each person only as the source system allows.

The integration is the same code in both homes. Only three things differ: the store it writes to, where its token is kept, and what wakes it up.

See where each one runs

orchestra integrations

For each integration it prints where it runs for the folder you are in, who it acts as, what it stores and where, the connected account and the last sync, and the one command that moves it. In the web app and in the desktop app on a hosted workspace, Settings, Integrations shows one card per integration: who it is connected as, what it brings in, its last sync, and whether it can write. In the desktop app on Orchestra Local, connect Linear under Settings, This machine, with a Linear API key. On a laptop using Orchestra Local, a repo your team has moved to Orchestra’s cloud is served by the cloud, so orchestra integrations in that repo shows the cloud’s integrations, and in any other repo it shows the laptop’s.

What each integration does in each home

Integration	On this laptop, it acts as	In Orchestra’s cloud, it acts as
Linear	You, with your own Linear account	The workspace’s Linear connection
GitHub	You, with your own GitHub login (`gh` or a device sign-in)	The Orchestra GitHub App installed on your organization
Pull request context	You, with your own GitHub login	The Orchestra GitHub App
Commit links	Your git, through the post-commit hook	Your git, through the post-commit hook
Knowledge from repository files	This laptop, reading your clone	The Orchestra GitHub App

What is stored, and where

Integration	On this laptop	In Orchestra’s cloud
Linear	Issues, comments and states for the teams you can see, in this laptop’s log only	Issues, comments and states, visible as Linear allows
GitHub	Repositories, pull requests, reviews, commits, and issues with their comments, for repos you work in, in this laptop’s log only	Repositories, pull requests, reviews and commits, visible as GitHub allows
Pull request context	Nothing beyond the pull request description it writes	Nothing beyond the pull request description it writes
Commit links	Which session made each commit, in this laptop’s log only	Which session made each commit
Knowledge from repository files	Docs written from your repository files, in this laptop’s log only	Docs written from your repository files

On a laptop, a token is kept in the macOS keychain or libsecret (a file only you can read where neither exists), never on Orchestra’s servers. Because each person connects as themselves, a laptop only ever holds what its owner can see in the source system. Your teammates’ views come from their own connections, never from a copy of yours.

What it writes back

Linear sends the issue updates you make: with your own token on a laptop, with the workspace connection in the cloud.
GitHub and pull request context write the context section of a pull request description: as you on a laptop, as the App in the cloud.
GitHub Issues, on a laptop only: a change you make in Orchestra to an issue that lives on GitHub (its title, description, labels, closing or reopening it, a comment) is made on GitHub as you, through your own gh login. To open a new issue on GitHub from Orchestra, name the repository as the team (owner/name); otherwise a new issue stays in Orchestra. Priority, project, parent and assignee are not written to GitHub, and Orchestra says so instead of saving half a change.
Commit links and Knowledge from repository files write nothing back.

Limits on a laptop

No webhooks. Linear and GitHub tell a server the moment something changes by calling a public address (a webhook). A laptop has no public address, and a webhook would send your issues to a public server. So on Local your laptop asks instead: when you open Issues or an agent reads or writes an issue (if the last sync is more than 30 seconds old), right after a teammate’s laptop changes something, and every 10 to 15 minutes while the desktop app or the terminal client is open (less often when you are away or on battery). With no app open it does not ask at all. In the cloud, changes arrive as they happen.
GitHub issue refs. A GitHub issue is shown as the repository’s name and its number, such as APP-12 for issue 12 of acme/app. Two repositories with the same name under different owners would share that prefix.
Only while the laptop is on. A laptop that is asleep does not sync; it catches up from where it stopped when it wakes.
Your account only. A laptop syncs what your account can see, not what the whole organization can.

Move to Orchestra’s cloud

For your own laptop:

orchestra cloud

For a repo, or your whole team, a team admin runs orchestra promote. See Moving between Local and hosted for the preview and the consent it asks for first. What happens at each step:

Step	Linear	GitHub	Pull request context, commit links	Knowledge from repository files
On your laptop, before the move	Your own sign-in or key, in the keychain. Your laptop polls issues, comments and states for your teams, and writes back as you	Your own `gh` login or device sign-in. Your laptop polls repositories, pull requests, reviews and commits for repos you work in	Your own login, and the post-commit hook	Read from your clone
The upload	Every event already on your laptop is uploaded unchanged, with its id, along with where sync had got to	The same	The same	The docs written on your laptop are uploaded as they are
The workspace connects once	Linear workspace connection. Its first sync recognizes what you uploaded and picks up from where your laptop stopped, rather than reading everything again	The GitHub App install, with the same first sync	The cloud reads through the App	Knowledge reads the App’s copy of the repo
Your laptop after the move	Sync stops, and the token is deleted from your keychain. Reads and writes go through Orchestra’s cloud	The same	The same (the hook keeps recording commits, now sent to the cloud)	Stops writing docs on the laptop

Nothing is lost or counted twice. Every event keeps the id it had on your laptop, and every issue, pull request and commit is recognized by the id the source gave it, so the same object seen from three laptops is one object in the cloud. In the cloud, who can see an integration’s content follows the source system’s own permissions, never a broader default.

Move back to this laptop

For your own laptop:

orchestra local

For a repo or the team, a team admin runs orchestra demote, and each person brings the export onto their laptop with orchestra local import <file>. The export carries every event and where each sync had got to. After you reconnect your own account, your laptop resumes from that point, with no gap in history.

Integrations that run only in the cloud

An integration with no laptop version is shown as Cloud only in orchestra integrations, with the reason. Every integration offered today runs in both homes. Slack, Jira and Google Drive have no connector yet, so they are not offered in either.

Start here

Teams

Using Orchestra

Integrations