Getting started

Set up Terrastore — install the Runsheet GitHub App, enrol a repo, point Terraform at it. The same setup works locally and in CI.

1. Sign in to the console

Sign in with GitHub at console.runsheet.dev. The first sign-in creates your billing account.

2. Install the Runsheet App

From Add an org in the console, install the App on the GitHub org you want to manage state for. You need to be a GitHub admin of that org.

When GitHub asks “All repositories” or “Only select repositories”, either works — Runsheet only bills for the repos you explicitly enrol later.

3. Enrol a repo

From the org dashboard, click Add a repo and pick one. Enrolment is the $1-per-repo-per-month decision: repos you don’t enrol won’t be billed and won’t accept state writes.

4. Drop in the cloud block

In your repo’s Terraform configuration:

terraform {
  cloud {
    hostname     = "terrastore.runsheet.dev"
    organization = "<your-github-org>"
    workspaces {
      name = "<repo>.<workspace>"
    }
  }
}

The workspace name is <repo>.<workspace>. Append __<stage> to pin a stage explicitly; otherwise the server default applies for local runs, and CI gets the stage from its environment: field.

5. Pick a path

Locally

terraform login terrastore.runsheet.dev
terraform init
terraform apply

The browser opens, you authorize, and a bearer is saved to ~/.terraform.d/credentials.tfrc.json. Revoke it any time from the console’s token page.

GitHub Actions

name: terraform

on:
  push:
    branches: [main]

permissions:
  id-token: write   # mint OIDC tokens
  contents: read

jobs:
  apply:
    runs-on: ubuntu-latest
    environment: prod   # the name becomes the stage
    steps:
      - uses: actions/checkout@v4
      - uses: runsheet-actions/terrastore-auth@v1
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform apply -auto-approve

The runsheet-actions/terrastore-auth action mints the job’s GitHub OIDC token for Terrastore and exposes it to the Terraform steps as TF_TOKEN_<hostname>. environment: becomes the stage — wire it to a GitHub Environment for required-reviewer protection on prod.

Common gotchas

• 403 “this repo is not enrolled” — install the App on the org first, then enrol the repo in the console.
• 403 “you must be a GitHub admin” — only org admins can claim an org for a billing account. Org members can still use repos that are already enrolled.
• Local runs landing in the wrong stage — pin the stage with the __<stage> suffix on the workspace name.

Stuck? Drop us a note.