Quickstart

Go from sign-up to a reviewed, applied run in about fifteen minutes. Use a non-production cloud account the first time.

Before you start

• A GitHub repository with an OpenTofu configuration and a committed .terraform.lock.hcl.
• Permission to install a GitHub App on that repository.
• A cloud account (AWS, Google Cloud, or Microsoft Azure) where you can create an IAM role or service account.

1. Sign in and create an organization

1. Go to stackship.run and sign in with email or Google.
2. Create an organization, or accept an invitation to an existing one.

The Get started page tracks the steps below. Reopen it from Help in the sidebar.

2. Connect GitHub

1. On Get started, select Install GitHub App.
2. In GitHub, choose only the repositories StackShip should read, then install.
3. When GitHub asks, authorize StackShip with your GitHub account. StackShip connects the installation only if your GitHub account can access it.

The App asks for read access to metadata, contents, and pull requests, and write access to checks. It can’t push code or comment on pull requests. See GitHub source connections.

Only organization owners and admins can install the App.

3. Create a project

1. Go to Projects and select Create project.
2. Enter a name such as Platform.

Projects don’t change who can access their workspaces.

4. Create a workspace

1. Go to Workspaces and select Create workspace.
2. Enter a name such as network-foundation and choose your project.
3. Keep the default North America East execution region, or choose the region closest to your infrastructure. Keep the default OpenTofu version (the newest supported release), or pick an exact version.
4. Select Create workspace.

5. Connect the repository

1. Open the workspace’s Source tab.
2. Choose the repository, the tracked branch (for example main), and the working directory that contains your configuration.
3. Optionally add trigger paths so only relevant changes start runs.
4. Select Save source.

6. Add cloud credentials and variables

1. Go to Credentials, select Create credential profile, and choose your cloud provider.
2. Add a version with your role details, apply the generated trust template in your cloud account, then select Verify version.
3. On the workspace’s Variables tab, add any OpenTofu inputs or environment variables. Turn on Sensitive value for secrets — they become write-only.

See variables and secrets for provider-specific steps.

7. Start a run

Push a commit to the tracked branch. StackShip plans the change, evaluates any attached policy, and waits for approval. A pull request instead creates a plan-only preview that can never apply.

You can also start runs from the tofu CLI (see step 9) or the REST API.

8. Review and approve

1. Open the run from Runs or from the GitHub check.
2. Review the planned changes, policy results, and logs.
3. Select Approve plan to apply, or Discard run to stop.

Approvals expire after seven days. If the plan changes while you review, the page asks you to refresh before your decision counts. See approvals.

9. Optional: use the tofu CLI

To run tofu against the workspace from your machine, add a cloud block and sign in:

terraform {
  cloud {
    hostname     = "stackship.run"
    organization = "your-org-slug"

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

tofu login stackship.run
tofu init
tofu plan

The workspace’s CLI access tab shows the exact block to copy.

Next steps

• Core concepts
• Run lifecycle
• Policy sets
• Migrate existing state