Quickstart

Install the GitHub App, create a project and OpenTofu workspace, and inspect a managed run.

This walkthrough uses the dashboard and a small GitHub repository. Use a non-production cloud account and an OpenTofu configuration you are allowed to apply.

Before you start

OpenTofu 1.6.0 or newer (any exact stable release).
A GitHub repository containing a committed .terraform.lock.hcl.
Permission to install the StackShip GitHub App on that repository.
A cloud role suitable for federation, or the explicitly documented write-only generic-secret option when it is enabled.

GitLab, Bitbucket, Terraform binaries, and customer-operated execution agents are not available today.

Open stackship.run, sign in, and create or select your organization. The active organization is the tenant used by every subsequent dashboard request.

When you create an organization, the URL slug is suggested from the name and stays editable. If your account has no organizations yet, either create one or ask an organization admin for an invitation; the selection screen also offers sign-out so you can switch accounts.

Once you are in, the account menu at the right end of the page header shows who you are signed in as and which organization is active, switches between your organizations, and signs you out.

After selection, the dashboard overview leads with run health: counts of runs awaiting approval, needing recovery, or failed, each linking into the filtered runs inventory. The Get started page lists the three setup steps below — connect GitHub, create a project, and create a workspace — and marks the steps that are already complete.

2. Create a project

Create a project such as Platform. A project is a grouping for workspaces, not a separate tenant.

The URL slug is derived from the name as you type and stays editable. When creation succeeds, the dashboard opens the new project’s page directly, so there is no separate confirmation step to acknowledge.

3. Install the GitHub App

Start installation from onboarding or the workspace source page. Select only the repositories StackShip should read. The App requests:

metadata read;
contents read;
pull-requests read; and
Checks write.

StackShip does not request repository write or pull-request comment permissions.

When installation finishes, GitHub returns you to the dashboard’s Get started page with the Connect GitHub step shown as complete. The step reflects the real installation status from the API: a connected installation shows the connected GitHub account login, and a suspended installation shows an attention notice asking you to reinstate the App in GitHub while keeping the install action available. If the status cannot be checked, the page says the status is unavailable rather than claiming the App is not installed. Members without the install permission see a read-only notice there instead; an organization admin can install or reconnect the App.

4. Create a workspace

Create network-foundation in the project. Choose:

the us execution region; and
one exact supported OpenTofu version.

The form preselects the us region and defaults the OpenTofu version to the newest supported release; both stay editable. The workspace slug is derived from the name as you type. As with projects, successful creation opens the new workspace’s page directly.

The workspace schema also recognizes eu, but that region is disabled at launch until EU execution capacity is available. StackShip does not fail an EU selection over to US.

Then configure its source:

repository;
tracked branch, for example main;
repository-relative working directory; and
optional monorepo trigger paths.

5. Configure inputs

Add non-sensitive Terraform or environment variables on the workspace. Mark credentials and tokens sensitive; the value becomes write-only after submission.

For cloud access, prefer a versioned AWS, Azure, or Google Cloud federation profile. Create a phase-appropriate version, apply the generated trust template in the cloud account, and verify it before running.

Never configure a generic secret for a speculative pull-request run.

6. Start a run

A push to the tracked branch creates a managed run. A pull request targeting that branch creates a speculative plan and policy evaluation that cannot apply.

You can also create a managed run from the authenticated native v1 API. The separate StackShip CLI is not available today.

7. Review and decide

Open the run page and inspect:

immutable run and configuration identities;
sanitized plan counts;
policy results;
the exact approval binding; and
streamed logs.

A plan_and_apply run waits at awaiting_approval. Approve or reject only after reviewing the current evidence. If the evidence changes, StackShip rejects the stale decision and asks you to refresh.

The run page displays the exact persisted approval deadline in UTC. The window is seven days. After it passes, StackShip marks the run expired, rejects both approve and reject with 409 APPROVAL_EXPIRED, and requires a new run.

8. Inspect state

After a successful apply, the workspace state page lists the new immutable version. Raw state download is authenticated, audited, capped at 100 MB, and streamed through the Worker rather than exposed as an R2 URL.

Optional: configure native OpenTofu cloud access

For local cloud-protocol operations, authenticate:

tofu login stackship.run

Use the native cloud block:

terraform {
  cloud {
    hostname     = "stackship.run"
    organization = "example"

    workspaces {
      name = "network-foundation"
    }
  }
}

StackShip discovery routes that hostname to https://api.stackship.run/api/v2/. It is not a generic HTTP backend.