The Terraform and OpenTofu cloud block, explained

What the cloud block is

The cloud block, inside the top-level terraform block, tells OpenTofu or Terraform to keep state on a remote platform and run plans and applies there. It is the successor to the older remote backend, and any platform that implements the protocol works with it, including Terraform Cloud and StackShip.

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

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

OpenTofu keeps the terraform block name for compatibility, so the same file works with both tools.

The arguments

The cloud block vs a backend

A backend block, such as s3, only stores state; plans and applies still run wherever you type the command. With the cloud block, tofu plan and tofu apply run remotely with the workspace's variables and credentials, and stream their output to your terminal. A configuration has one or the other, never both.

Signing in with tofu login

tofu login stackship.run
tofu init

tofu login opens a browser, you sign in, and the token is saved in your CLI credentials file. Every later command, including downloads from a private module registry on the same host, uses it.

Tokens for CI: TF_TOKEN_ variables

In CI there is no browser. Store a token as a secret and expose it as an environment variable named after the host:

export TF_TOKEN_stackship_run='<token>'
tofu init -input=false
tofu plan -input=false

The variable name is TF_TOKEN_ followed by the hostname, with dots replaced by underscores. Dashes in a hostname become double underscores. OpenTofu and Terraform both read these variables.

In StackShip, create the token on the workspace's CLI access tab and pick its purpose: Remote plan and apply for pipelines, or State migration for a one-time import. Tokens are limited to one workspace and expire after 1 to 365 days; choose the shortest that works.

Common errors

Switching platforms

Because the protocol is shared, moving a workspace from Terraform Cloud to StackShip is a hostname change plus a state push. The migration guide has the steps, and the OpenTofu CLI docs list every command.