Connect GitHub

Rift builds VMs from repositories, and the way it's given them is GitHub's App installation: you install Rift's App on a GitHub account and pick the repositories it may see. Installing binds those repositories to your Rift organization; enabling turns Rift on for the account. This page is both steps, and what they set up.

Which GitHub account goes where is fixed by kind:

• your personal organization connects your own GitHub user;
• a team connects a GitHub organization — a company's repositories belong to its team, where colleagues can be invited.

The other way round is refused when GitHub sends you back, with the step that fixes it.

Your personal organization connects your own GitHub user, and Rift has to know which one that is: link it first through your agent with rift_github_login, the device flow that also lets your VMs push as you. rift_github_connect personal refuses until you have, and GitHub's page back refuses an installation by any other GitHub user — so a personal install link someone forwards can't put their account in your organization, or yours in theirs.

Install the App

You need to be an admin of the Rift organization. Ask your agent for the install URL:

rift_github_login                  # once, before connecting personal
rift_github_connect  personal
rift_github_connect  acme-inc

or, in the app, click Connect a GitHub account on the organization. Either gives a URL carrying a signed state that names your organization, good for an hour. Open it in a browser signed in to GitHub, choose the account, and choose the repositories:

• Only select repositories — pick the ones you'll want VMs of. The tidiest choice, and one you can extend later on GitHub.
• All repositories — everything the account has now and later.

Install. GitHub asks you to authorize Rift, which is how Rift knows it was you who installed it, then sends you back to a page asking you to confirm: which GitHub account goes to which Rift organization, and who made the link you installed from. Confirm, and the installation is bound to your organization. Only the GitHub user who installed the App, and who can still reach it, can do this — and on a GitHub organization, only an owner can install it. An installation made before Rift kept who installed it has to be uninstalled and installed again. From then on the App's webhook keeps Rift current: a repository added to the installation appears, one removed disappears, and every push to a watched branch is heard.

When you aren't an owner

For a team, rift_github_connect and the app also give an owner link, and so does GitHub's "request sent" page if you try to install anyway. Send it to an owner of the GitHub organization. It's good for 7 days, and they don't need a Rift account: it opens a page naming your team, its admins and you, with a button to install Rift on GitHub. They install, confirm on the page GitHub sends them back to, and the account appears under the team, in rift_whoami and on the Organizations page, for you to enable.

If the owner already approved your request on GitHub's own screen, GitHub doesn't tell Rift which team it was for; they open the owner link anyway and choose Connect it, which asks GitHub who they are and offers the installations they made that are waiting to be connected. The link stops working if you stop being an admin of the team.

Enable Rift for the account

An installed account starts disabled. rift_whoami lists it under its organization, and so does the Organizations page, under GitHub accounts. Turn Rift on through the agent:

rift_github_enable  acme-inc  <account>

or in the app, with Enable on the account's row. Disable, in the app, is the reverse: the installation stays, and its repositories are listed, but no ref of theirs can be watched and no VM built until it's enabled again.

See what the App covers

rift_repos  acme-inc

Every repository the installation covers, its account, whether Rift is enabled for that account, and the refs being watched. The app's Repositories page shows the same. Repositories are named github:<owner>/<name> everywhere in Rift — that's the id rift_watch and rift_vm_new take.

Where to go next:

• Watch a ref — the step that makes a repository build.
• Push from a VM — your own GitHub account, connected so that what an agent pushes is yours.