GitHub and previews

Connecting GitHub

The first time you connect GitHub, Orbit asks GitHub to create an App for this server. When you install it, GitHub asks where (your account or one of your organizations), and the App can only read the repositories you choose there.

• Why the App is public: GitHub only installs a private App on the account that created it. Public only means it can be installed elsewhere. Anyone can see its page, but its key stays on your server, and Orbit only uses the installation that the GitHub user connecting from your console confirms.
• Owned by an organization: Orbit can create the App under an organization ("Have an organization own the App instead") if the organization wants it in its own settings.
• Name and logo: the App is named "Orbit <server name>", which you can change before creating it; GitHub requires a name no other App uses. GitHub only accepts a logo through the App's settings page, so Settings → Integrations offers Orbit's logo and links to that page.
• One installation at a time: to read another account's repositories, disconnect and connect again, choosing that account.
• Addresses: GitHub sends you back to the address you used when you created the App, so create it from https://orbit.<server-ip-with-dashes>.sslip.io rather than through an SSH tunnel. If you later reach Orbit at another address, update the App's callback URL on GitHub to <new address>/github/callback.
• Where its key lives: the App's private key and secrets are sealed in Orbit's secret store and travel with orbit backup. Disconnecting forgets the installation but keeps the App. Deleting the App on GitHub makes Orbit create a new one the next time you connect.

Deploying on push

• The App sends every push to https://orbit.<server-ip-with-dashes>.sslip.io/github/webhook, signed with a secret only your server knows.
• A push to an application's branch deploys that commit when Deploy automatically is on in the application's settings. The same delivery twice deploys once.
• For Apps created by older versions, turn on their Push event on GitHub (Permissions & events → Subscribe to events); Settings → Integrations says so while it is off.

Pull request previews

Turn previews on in a project's Previews, next to its environments, and choose the long-lived environment they copy and how many can run at once (3 by default, at most 10).

Every pull request opened from a branch of a repository that environment builds gets a preview named after it (pr-12):

• the services built from that repository, deployed from the pull request's branch, with the source's variables and secrets;
• empty copies of the databases those services reference, without backups, so a preview never reads or writes your real data;
• its own namespace and generated address (<service>-pr-12-<project>.<server-ip-with-dashes>.sslip.io).

Pushes to the branch redeploy the preview. Closing or merging the pull request removes it with its data, and Remove does the same by hand.

• Forks: pull requests from forks never get a preview, so code from outside the repository never runs on your servers.
• The limit: past it, a pull request gets its preview on its next push once another one closes. Turning previews off keeps the open ones until their pull requests close.
• Older Apps: previews need Pull requests: read and the Pull request event. Add both on GitHub (Permissions & events), then accept the new permission on the installation; the Previews page says so while the event is missing.