Workspaces

Workspaces are the core of TerraDesk — each one is a unit of Terraform state, bound to a path in a GitHub repository, with its own container configuration and approval requirements. On this page we'll look at how to retrieve, create, update, and delete workspaces through the API.

Workspaces can also be managed with Terraform using the official provider: devhub_terradesk_workspace. That is usually the better fit — the repository that defines your infrastructure also defines the workspaces that plan it.

All of these endpoints require an API key with full access. See Authentication.

The workspace model

Properties

Name
id
Type
string
Description
Unique identifier for the workspace, prefixed tfws_.
Name
name
Type
string
Description
The display name for the workspace.
Name
repository
Type
string
Description
The GitHub repository holding the Terraform, in owner/name form. Must be visible to the GitHub integration.
Name
path
Type
string
Description
The directory within the repository that Terraform runs in. Defaults to the repository root.
Name
trigger_paths
Type
array
Description
Additional repository paths that also start a plan when a push or pull request changes a file under them. Each entry is an object with a path. Additive and prefix-matched — they never stop path itself from triggering, and only decide whether to plan, never where Terraform runs.
Name
docker_image
Type
string
Description
The image the init, plan, and apply containers run, for example hashicorp/terraform:1.10.
Name
command
Type
string
Description
Replaces the image's entrypoint on the init, plan, and apply containers, for example op run -- terraform. The Terraform arguments are appended unchanged. Blank uses the image's own entrypoint.
Name
init_args
Type
string
Description
Extra arguments passed to terraform init. -input=false is always added.
Name
init_containers
Type
array
Description
Containers that run after checkout and before terraform init, in order. Each has a name, an image, and an optional command.
Name
run_plans_automatically
Type
boolean
Description
Whether pushes and pull requests queue plans for apply automatically. Defaults to false.
Name
required_approvals
Type
integer
Description
The baseline number of approvals for resource changes no resource policy sets a count for. A resource policy with an explicit count replaces it for the resources it governs. Defaults to 0.
Name
cpu_requests
Type
string
Description
CPU requested for the run's pod, in Kubernetes units. Defaults to 100m.
Name
memory_requests
Type
string
Description
Memory requested for the run's pod, in Kubernetes units. Defaults to 512M.
Name
env_vars
Type
array
Description
Plaintext environment variables exposed to every container. Each has a name and a value.
Name
secrets
Type
array
Description
Encrypted values delivered to the run. Each has a name and a raw flag; raw exposes it under its literal name instead of TF_VAR_<name>. Values are never returned — only id, name, and raw.
Name
workload_identity
Type
object
Description
Google workload identity configuration: enabled, service_account_email, and provider.
Name
tunnel_id
Type
string
Description
The Tunnel this workspace's jobs run through, for infrastructure in a cluster Devhub cannot reach directly.
Name
slack_channel
Type
string
Description
Where a plan posts when it reaches planned and is waiting on a human.
Name
slack_notify_on
Type
string
Description
Which plans post to slack_channel: all_plans or default_branch. Defaults to all_plans.
Name
drift_detection_enabled
Type
boolean
Description
Whether a scheduled refresh-only drift run happens for this workspace. Defaults to false.
Name
drift_cron_expression
Type
string
Description
When drift detection runs, in UTC. Required when drift_detection_enabled is true.
Name
drift_slack_channel
Type
string
Description
Where a drift run posts, and only when it finds drift.
Name
inserted_at
Type
timestamp
Description
Timestamp of when the workspace was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the workspace was last updated.

POST/api/v1/terradesk/workspaces

Create a workspace

Creates a workspace. The repository must already be visible to the GitHub integration; if it isn't, the request fails with a repository not found error.

Required attributes

Name
name
Type
string
Description
The display name for the workspace.
Name
repository
Type
string
Description
The GitHub repository in owner/name form.
Name
docker_image
Type
string
Description
The image to run Terraform with.

Optional attributes

Every other property in the workspace model may be supplied.

Request

POST

/api/v1/terradesk/workspaces

curl https://xxx.devhub.cloud/api/v1/terradesk/workspaces \
  -H "x-api-key: dh_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod",
    "repository": "acme/infrastructure",
    "path": "environments/prod",
    "docker_image": "hashicorp/terraform:1.10",
    "required_approvals": 2
  }'

Response

{
  "id": "tfws_abc123def456",
  "name": "prod",
  "repository": "acme/infrastructure",
  "path": "environments/prod",
  "trigger_paths": [],
  "docker_image": "hashicorp/terraform:1.10",
  "command": null,
  "init_args": null,
  "init_containers": [],
  "run_plans_automatically": false,
  "required_approvals": 2,
  "cpu_requests": "100m",
  "memory_requests": "512M",
  "env_vars": [],
  "secrets": [],
  "workload_identity": null,
  "tunnel_id": null,
  "slack_channel": null,
  "slack_notify_on": "all_plans",
  "drift_detection_enabled": false,
  "drift_cron_expression": null,
  "drift_slack_channel": null,
  "inserted_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

GET/api/v1/terradesk/workspaces/:id

Retrieve a workspace

Retrieves a workspace by its ID. Archived workspaces are not returned.

Request

GET

/api/v1/terradesk/workspaces/tfws_abc123def456

curl https://xxx.devhub.cloud/api/v1/terradesk/workspaces/tfws_abc123def456 \
  -H "x-api-key: dh_xxx"

Response

{
  "id": "tfws_abc123def456",
  "name": "prod",
  "repository": "acme/infrastructure",
  "path": "environments/prod",
  "trigger_paths": [{ "path": "modules" }],
  "docker_image": "hashicorp/terraform:1.10",
  "required_approvals": 2,
  "secrets": [
    { "id": "tfsec_xyz789", "name": "database_password", "raw": false }
  ],
  "inserted_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

PATCH/api/v1/terradesk/workspaces/:id

Update a workspace

Updates a workspace. repository must be supplied on every update, even when it isn't changing.

env_vars, secrets, init_containers, and trigger_paths are replaced wholesale by what you send, not merged. Omitting one of these leaves it unchanged; sending an empty array clears it.

Request

PATCH

/api/v1/terradesk/workspaces/tfws_abc123def456

curl -X PATCH https://xxx.devhub.cloud/api/v1/terradesk/workspaces/tfws_abc123def456 \
  -H "x-api-key: dh_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "acme/infrastructure",
    "required_approvals": 3,
    "drift_detection_enabled": true,
    "drift_cron_expression": "0 2 * * *"
  }'

DELETE/api/v1/terradesk/workspaces/:id

Delete a workspace

Archives a workspace. It stops running and no longer appears in the workspace list, but its plans — and the record of who approved them — are kept.

Request

DELETE

/api/v1/terradesk/workspaces/tfws_abc123def456

curl -X DELETE https://xxx.devhub.cloud/api/v1/terradesk/workspaces/tfws_abc123def456 \
  -H "x-api-key: dh_xxx"