OrbitsDocs
esc
    Open Orbits
    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

    GitHubGitLab.comBitbucket Cloud
    How it connectsThe Orbits GitHub App, installed on an account or organisationYour OAuth consentYour OAuth consent
    Deploy on pushYesYesYes
    Previews for branches and pull or merge requestsYesYesYes
    Commit status Orbits – <project>YesYesYes
    Repository website set to the free addressYesNoNo
    "Ready to deploy" email for new repositoriesYesNoNo

    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 api and read_repository scopes. 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 as group/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:

    SettingWhat it does
    Production branchThe branch that deploys to production.
    Deploy every pushOff, pushes build nothing; you deploy by hand.
    Preview pull requestsOff, only the production branch builds.
    Comment on pull requestsStored, 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:

    DeploymentStatus on the commit
    Queued or buildingPending: "Queued", "Building"
    ReadySuccess: "Preview ready" or "Deployed to production"
    FailedFailure: "Build failed"
    CanceledError: "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.

    SwitchWhat it does
    Comment with a preview linkNot available yet: Orbits doesn't post comments on pull requests.
    Report deploy status as a checkCommit statuses, and on GitHub the repository website. On by default.
    Build pull requests from forksForks' 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.

    Was this page helpful?

    Updated