---
title: "Workspaces"
description: "OpenTofu configuration, state, runs, sources, variables, credentials, and policy grouped by project."
---

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

# Workspaces

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](/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](/workspaces/vcs).

## OpenTofu native cloud

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

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

## Related pages

- [Projects and organizations](/start/concepts)
- [GitHub source connections](/workspaces/vcs)
- [Variables and secrets](/workspaces/variables)
- [State and migration](/workspaces/state)
- [Runs](/runs)

Source: https://docs.stackship.run/workspaces/index.mdx