Terraform / OpenTofu
Create a template#
- Go to Task Templates and click New Template.
- Select Terraform as the app type.
- Configure the template and click Create.
- Click Run.
Semaphore runs terraform init automatically before each run, so a fresh clone works without extra steps.
Passing variables#
Variables from the selected Variable Groups are injected as environment variables. Terraform only reads an environment variable as an input variable when it is prefixed with TF_VAR_:
| Variable group key | Terraform variable |
|---|---|
TF_VAR_region |
var.region |
TF_VAR_instance_type |
var.instance_type |
Put anything sensitive — cloud tokens, credentials — on the Secrets tab of the variable group rather than in the JSON body. Those values are encrypted at rest and only exist in the process environment while the task runs.
A full worked example, including marking the variable sensitive on the Terraform side, is in Inventory and variables.
Workspaces#
Semaphore supports Terraform/OpenTofu workspaces natively, so one template can manage several environments from the same code. Creating and switching workspaces, and using SSH keys for private modules, are covered in the upstream workspaces guide.
State#
By default, state is handled by whatever backend your Terraform code declares — local, S3, GCS, Azure Blob, and so on. Semaphore does not interfere.
Built-in HTTP backend (Pro)#
On Pro, Semaphore ships an HTTP state backend and a template can override the backend to use it — without editing your Terraform code. That gives you state storage, locking and history inside Semaphore for teams that would otherwise have to stand up a state bucket first. See the upstream HTTP backend guide.
Destroy and state migration#
The run dialog exposes two toggles:
-destroy— tear down what the configuration manages.-migrate-state— move state when the backend changes.
Both are per-run, not per-template. Consider restricting who can start this template: on Enterprise, a custom role can grant run on a plan template without granting it on the destroy-capable one.
Next steps#
- Inventory and variables — the
TF_VAR_convention in full - Key Store — storing cloud credentials
- Runners — running Terraform from inside the network it manages