---
title: "Quickstart"
description: "Install the GitHub App, create a project and OpenTofu workspace, and inspect a managed run."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackship.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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.

## 1. Sign in and select an organization

Open [stackship.run](https://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:

```bash
tofu login stackship.run
```

Use the native cloud block:

```hcl
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.

## Next

- [GitHub source connections](/workspaces/vcs)
- [Run lifecycle](/runs/lifecycle)
- [Policy sets](/governance/policies)
- [Migrate state](/start/migrate)

Source: https://docs.stackship.run/start/quickstart/index.mdx