Build and deployGit providers
Deploy from Git
Connect GitHub, GitLab.com or Bitbucket Cloud to a team, deploy on every push, get previews for pull requests, and see each build's status on the commit.
A team connects its Git provider once, under Integrations or from the Import step of New project. After that, any project imported from that provider deploys on every push. Connecting and disconnecting are for owners and admins.
Providers
| GitHub | GitLab.com | Bitbucket Cloud | |
|---|---|---|---|
| How it connects | The Orbits GitHub App, installed on an account or organisation | Your OAuth consent | Your OAuth consent |
| Deploy on push | Yes | Yes | Yes |
| Previews for branches and pull or merge requests | Yes | Yes | Yes |
Commit status Orbits – <project> | Yes | Yes | Yes |
| Repository website set to the free address | Yes | No | No |
| "Ready to deploy" email for new repositories | Yes | No | No |
Self-managed GitLab is not available yet, and neither is GitBucket (it shows as Soon).
Connect GitHub
Press Continue to GitHub. GitHub shows its own screen: pick the account or organisation and the repositories Orbits may see (all, or only selected ones), then GitHub sends you back to Orbits.
The App reads your code, adds webhooks and reports statuses. To change which repositories Orbits can see later, use Change on GitHub on the GitHub integration page. A team has one GitHub installation.
The integration page shows the connected account, how many repositories Orbits can see, and how many webhook deliveries arrived this month.
Connect GitLab or Bitbucket
Press Continue to GitLab or Continue to Bitbucket, approve Orbits on the provider, and you come back to Orbits.
- GitLab asks for the
apiandread_repositoryscopes. Orbits lists the GitLab projects where you are Maintainer or above, since it adds a webhook to each project you import. Projects in subgroups keep their full path, such asgroup/subgroup/app. - Bitbucket shows the Orbits app's permissions: your account, repositories and pull requests (read), and webhooks (read and write). Orbits lists the repositories you administer, in every workspace you belong to.
The connection is the grant of the person who connected it: Orbits acts as them. If that person revokes Orbits on the provider, or loses access to the repositories, the connection shows needs attention and pushes stop deploying. Someone with access connects again to repair it. The integration page's link to the provider shows where that person can see or revoke Orbits' access.
When you import a repository, Orbits adds a webhook to it. If the connected person can't add one there, the import is refused.
Deploy on push
With a project imported, each push decides what to build:
- A push to the production branch builds a production deployment, which goes live when it's ready.
- A push to any other branch builds a preview of that branch, when previews are on.
Both are project settings, under Git in the project's settings:
| Setting | What it does |
|---|---|
| Production branch | The branch that deploys to production. |
| Deploy every push | Off, pushes build nothing; you deploy by hand. |
| Preview pull requests | Off, only the production branch builds. |
| Comment on pull requests | Stored, but posting the preview link on the pull request is not available yet. |
When a branch has an open pull request (a merge request on GitLab), its previews carry the pull request's number. See previews.
The same commit is never built twice at once: a push of a commit that is already queued or building is skipped.
Commit statuses
Every deployment of a project from Git sets a status on its commit, named Orbits – <project slug> and linked to the deployment's page in the web app:
| Deployment | Status on the commit |
|---|---|
| Queued or building | Pending: "Queued", "Building" |
| Ready | Success: "Preview ready" or "Deployed to production" |
| Failed | Failure: "Build failed" |
| Canceled | Error: "Canceled" |
A status only ever moves forward, so a late update never puts an old state back. You can turn statuses off with Report deploy status as a check on the integration page.
Repository website on GitHub
When a production deployment of a GitHub project goes live, Orbits sets the repository's Website (in its About box on GitHub) to https://<project>.theorbits.app. It only replaces a website that is empty or already a theorbits.app address, so a website you set yourself stays. A custom domain doesn't replace the free address there yet. Report deploy status as a check turns this off too.
"Ready to deploy" email
On GitHub, when someone pushes to the default branch of a repository created in the last seven days that no project uses yet, and Orbits detects a framework in it, the team gets one email suggesting it be deployed. It goes to the team member whose email matches the pusher's, or else to the team's owners. Pushes by bots don't count.
Orbits only hears about repositories the GitHub App can see: an installation limited to selected repositories doesn't send this for a new repository until you add it.
Pull-request settings
The integration page of each provider has three switches under Pull requests (merge requests on GitLab). They save as you change them, and only owners and admins can change them.
| Switch | What it does |
|---|---|
| Comment with a preview link | Not available yet: Orbits doesn't post comments on pull requests. |
| Report deploy status as a check | Commit statuses, and on GitHub the repository website. On by default. |
| Build pull requests from forks | Forks' pull requests are ignored unless this is on. Leave it off unless you trust every contributor: a fork's build could read your preview environment variables. |
Disconnect a provider
Press Disconnect on the integration page. The dialog says how many projects stop deploying on push.
- GitHub: Orbits forgets the installation and uninstalls its GitHub App from the account.
- GitLab and Bitbucket: Orbits forgets the connected person's grant and removes the webhooks it added, as far as the provider still allows. The grant stays listed on the provider until that person revokes it there.
What keeps working: existing deployments, production and its domains. Your sites stay online. What stops: deploying on push, previews and pull-request statuses, until you connect the provider again.
Deleting a team disconnects its Git providers first.
Troubleshooting
A repository isn't in the list. On GitHub, the App can't see it: add it to the installation. On GitLab you need Maintainer or above on the project; on Bitbucket, admin on the repository. The list holds up to 500 repositories.
Pushes stopped deploying. Check the integration page: needs attention means connect again. Check the project's Deploy every push setting, and that the push was to a branch Orbits builds. After a rollback, production pushes still build but don't go live until you turn auto-deploy back on.
The API for all of this is in integrations.