Skip to content

Documentation · Getting started

Connect your account

Install the GitHub App for CI runners, and issue a token for infrastructure runs. The two halves connect separately.

The two halves connect separately, and neither depends on the other.

  1. Start the install. A new account's dashboard opens on Connect GitHub to get started; press Connect GitHub. Later, the same thing is the Connect button on the GitHub card on Settings.

  2. Install on GitHub. Press Install on GitHub. GitHub asks where to install the App: a GitHub organisation, or your own personal account. Both work.

  3. Choose the repositories. Pick the ones whose builds you want to move. You can change the selection at any time on GitHub.

  4. Come back. GitHub sends you back to the dashboard, and the GitHub card on Settings reads Connected, with the account and the repositories it covers.

If you install it on a GitHub organisation you do not own, GitHub asks the organisation's owners to approve it first. Nothing is connected until one of them does; once one has, connect again from the dashboard to finish.

Installing the App does not move any builds. Nothing runs on our runners until a workflow asks for one of our runner labels, and nothing runs at all until a card is on file: the dashboard says Add a card before anything will run until there is one. Add a payment method, under Billing on Settings, places a temporary authorisation to check the card and releases it. Free compute with internet egress attracts miners, and we would rather say why than pretend otherwise. Once the card is on file, jobs can start within a couple of minutes.

The App works on a personal GitHub account as well as on an organisation. We register a single-use runner on the repository a job belongs to, and GitHub allows that on a personal account's repositories as well as on an organisation's.

permissionlevelwhat we use it for
ActionsRead & writeRead a job's workflow run and logs. Write is used only to cancel a workflow run: one whose jobs we all refused, or one holding a job you stopped.
AdministrationRead & writeRegister a single-use runner on the repository for each job, and remove it afterwards.
ContentsRead & writeRead workflow files and branches. Write is used only by the migration pull request, which you open yourself.
Pull requestsRead & writeOpen the migration pull request, and comment test results on a pull request if you turn that on.
WorkflowsRead & writeThe migration pull request changes a file under .github/workflows/, which GitHub guards apart from other files.
MetadataReadList the repositories you chose. GitHub requires it of every app.

It subscribes to one event, Workflow job, which is how we learn a job is waiting. Manage on GitHub on the GitHub card opens the installation, where you can change the repositories it sees or remove it.

  • GitHub was disconnected from these settings. The App is still installed on GitHub. The Connect button on the GitHub card reconnects the same installation, and your history comes straight back.

  • The GitHub app was removed on GitHub. Press Connect to install it again. Your history and usage are kept.

  • The GitHub app is suspended on GitHub. Unsuspend it there, and the connection comes back by itself.

  1. Sign in to the dashboard and go to Settings.

  2. Press Connect on the Terraform card, below the GitHub one. An organisation is created for you on the engine and an API token is issued.

  3. Copy the token now. It is not stored anywhere we can read it, so this is the only time it can be shown. If you lose it, revoke it under Your Terraform API tokens on Settings; an owner or an admin can issue the organisation a token of its own, under The organisation's token.

Give the token to the CLI as an environment variable:

bash
export TF_TOKEN_tf_runners_io=<your token>

The variable name is Terraform's own convention: the hostname with dots replaced by underscores. Then point a configuration at us:

hcl
terraform {
  cloud {
    hostname     = "tf.runners.io"
    organization = "your-organization"

    workspaces {
      name = "your-workspace"
    }
  }
}

terraform init and then terraform plan. The run executes on our infrastructure and appears under Terraform in the dashboard.

Do not run terraform login tf.runners.io. Discovery advertises the endpoint, but the browser step of that flow is on a path the host does not serve, so it cannot complete. The dashboard is where tokens come from.