Workspaces

OpenTofu configuration, state, runs, sources, variables, credentials, and policy grouped by project.

A workspace is StackShip’s unit of OpenTofu execution and state custody. Every workspace belongs to one project and organization.

Launch settings

The native v1 workspace record contains:

Setting	Meaning
`project_id`	Project grouping that owns the workspace
`name`	Human-readable dashboard name
`slug`	Stable URL-safe dashboard selector
`cloud_name`	Unique organization-local OpenTofu cloud workspace name
`execution_region`	Explicit execution region, `us` or `eu`
`opentofu_version`	Exact stable OpenTofu release, `1.6.0` or newer
`settings_version`	Monotonically increasing immutable-settings version

Create also requires an idempotency key. Updating the execution region or OpenTofu version creates the next settings version. The same idempotent update may carry a new display name; the slug and cloud_name never change on a rename.

In the dashboard, every workspace page carries one horizontal section navigation directly under the page header: Overview, State, Variables, Source, Policies, CLI access, and Settings. The breadcrumb trail for these pages is rooted at the Workspaces inventory, with the owning project kept as a non-root crumb. The overview leads with a dense fact strip — latest run state, runs awaiting approval, current state serial and resource count, connected repository and branch, execution region, and OpenTofu version.

The Settings page at /workspaces/{workspace_id}/settings edits the name, OpenTofu version, and execution region through the idempotent native update endpoint and confirms the new settings version inline. Renaming changes only the display name: the URL slug and cloud_name stay fixed at creation, so dashboard links and OpenTofu cloud blocks keep working. A name that is already in use returns 409 WORKSPACE_NAME_TAKEN, which the dashboard reports beside the field; a blank name is rejected before any request is sent.

Any stable OpenTofu release from 1.6.0 up is supported, including releases published after your StackShip deployment. The first time any workspace selects a version, StackShip fetches the official release checksums, verifies the linux_amd64 archive, and freezes the version’s digests in an immutable toolchain pin; every later run verifies against that pin, never against re-fetched upstream data. StackShip does not resolve latest, prereleases, version ranges, or Terraform binaries.

Execution capacity is currently available in us only. An EU workspace remains pinned to eu, but managed run and policy launch fail closed while that regional control is disabled; StackShip never substitutes US.

Workspace surfaces

A workspace may own or select:

GitHub App source settings;
immutable configuration archives;
Terraform and environment variables;
verified, phase-scoped credential profile versions;
an attached immutable Rego policy version;
managed runs and their review evidence;
ordered sanitized logs and authorized artifacts; and
one state lineage with immutable versions.

The first release does not include variable sets, scheduled runs, drift settings, cost settings, workspace dependencies, or customer-operated execution agents. Private modules are published and consumed through the organization-level module registry; managed plans resolve them automatically with the run’s injected credential.

GitHub source

GitHub App is the only supported VCS provider. Source settings select a repository, tracked branch, repository-relative working directory, optional trigger paths, and optionally a separate speculative federation version.

Tracked pushes may create plan-and-apply runs. Pull requests targeting the tracked branch create speculative runs that can never apply. See GitHub source connections.

OpenTofu native cloud

OpenTofu resolves workspaces by organization and name through StackShip’s /api/v2 compatibility surface:

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

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

This is the native cloud contract, not the generic HTTP backend. The organization in configuration is an object selector; the live credential and its boundaries remain authoritative for authorization.

Use the workspace’s cloud_name in the cloud block, not its display name. Dashboard-created workspaces initialize cloud_name from the workspace slug, so display names may contain spaces without becoming invalid OpenTofu identifiers. Workspaces created through the compatibility API retain the exact valid OpenTofu workspace name as cloud_name; StackShip derives their lowercase URL slug separately by collapsing and trimming _ and - separators, with workspace as the nonempty fallback. StackShip enforces cloud_name uniqueness per organization in PostgreSQL. A compatibility create or rename that collides returns a JSON:API 422 resource_conflict response.

The 0023_workspace_cloud_name migration preserves an existing slug only when it is a valid, unique organization-local cloud name of at most 90 characters. Duplicate or overlong historical slugs receive the deterministic form workspace_<32-character-public-id-suffix> so the migration cannot fail on previously valid workspace data.

Serial execution and state

Managed runs and local cloud clients share one fenced workspace writer reservation. No second writer can publish state while the current fence is active. Every completed state write creates an immutable version; raw state remains available through authenticated, audited streaming.

Deleting a workspace

Deleting a workspace removes its configuration — tags, settings versions, variables and their versions, credential profiles, policy attachments, the state lineage, active locks and writer reservations, and GitHub source settings. Service-account tokens are retained as security evidence, but the deletion transaction revokes them and clears their workspace scope.

Execution history is kept as audit evidence and is never removed by a deletion. A workspace that still has state versions, state uploads, configuration versions, run input snapshots, artifacts, runs, source ingestions, or apply-recovery records returns 409 WORKSPACE_EXECUTION_HISTORY_RETAINED instead of being deleted. In practice, deletion is for unused workspaces; once execution or recovery evidence exists, the workspace remains as its audit anchor.

The retained-history check, token revocation and detachment, configuration cascade, and workspace deletion run in one serializable PostgreSQL transaction. Any failed constraint or concurrent change rolls back the whole operation. Workspace references are organization-scoped, so a row from one organization cannot attach to another organization’s workspace.

Access

Organization members can read workspaces and create runs. Owners and admins receive workspace administration, state-write and recovery, run-decision, credential-write, policy-write, and GitHub administration permissions. Unknown or stale roles receive no access.

The dashboard keeps workspace-variable metadata visible to members with workspace:read, but it renders create, replace, and delete controls only after the active organization role grants workspace:admin. A failed or unavailable role check is treated as read-only.