Connect Terraform
Tasks call HCP Terraform through qbash.integrations.terraform with an API token you store on the Connectors page. The connector reads organizations, workspaces, variables, variable sets, runs with their plans and applies, configuration versions, state versions and their outputs, projects and notification configurations. Its writes create and update workspaces and workspace variables, create variable sets and their variables, queue runs, create configuration versions and create projects.
It covers HCP Terraform (formerly Terraform Cloud) only. Self-hosted Terraform Enterprise and the open-source Terraform CLI are different products and are not supported. No method deletes anything, applies or discards a run, changes state, or manages teams and tokens.
After you connect Terraform, you can add its tools to a qbash MCP server for ChatGPT, Claude and other MCP clients, or call it from a Python task.
Get an HCP Terraform account
- Create an account at app.terraform.io. The sign-up form asks for a username, email address and password. HashiCorp's docs do not say whether the Free plan needs a credit card.
- Create an organization and choose the Free plan. It costs nothing for up to 500 managed resources, with one concurrent remote run. It includes unlimited workspaces and projects and API access, but not teams. Teams are a paid-plan feature, and so are policies and policy sets, which this connector does not cover.
- Open Account settings, then Tokens, and click Create an API token.
- Choose a short expiration, such as 30 days.
- Copy the token. HCP Terraform shows it once, so paste it straight into qbash or keep it somewhere safe.
- Confirm the token can write. In the organization, create a test workspace in the HCP Terraform UI, or run
create_projectfrom a task and check the project appears.
Essentials is pay-as-you-go per managed resource per hour, and HashiCorp's docs point to the pricing page on its Terraform site for current rates. Standard and Premium need a conversation with HashiCorp sales. HCP Europe organizations use contract billing through sales.
Pick a token type
HCP Terraform has no scopes, so the token's owner decides what qbash can do.
| Token | Permissions | Notes |
|---|---|---|
| User | The permissions of the user who made it | The practical choice on the Free plan, which has no teams |
| Team | The access of the team on its workspaces | Needs a paid plan. A team token can start runs and create configuration versions |
| Organization | Can create and configure workspaces and teams | Cannot start runs or create configuration versions |
Avoid a token from an organization owner. Create it from a user or team that has only the workspaces your tasks need. An organization can disable user tokens, and HCP Terraform then refuses them on that organization's resources.
The API allows 30 requests per second per user, counted across all of that user's tokens. Some endpoints allow fewer. List runs allows 30 requests per minute. A 429 reaches your task as a rate limit error, and the task should wait a few seconds before calling again.
Add the token in qbash
- Open Connectors, then Terraform, and click Connect.
- Fill in Credential Name, such as "qbash platform workspaces", and paste the token into API Token.
- Save. qbash checks the token with HCP Terraform and saves it only if HCP Terraform accepts it.
- In the task editor, choose Add connector from the Package + menu and select the credential. See Task resources.
Check recent runs from a task
workspaces = qbash.integrations.terraform.list_workspaces(organization="my-organization")
for workspace in workspaces["workspaces"]:
runs = qbash.integrations.terraform.list_runs(
workspace_id=workspace["id"],
status=["errored"],
page_size=5,
)
qbash.output({"workspace": workspace["name"], "errored_runs": runs["runs"]})
Each response is JSON:API flattened to plain keys. An item has id, type and its attributes with - changed to _, and a relationships map of related IDs. A run's relationships.plan and relationships.apply go to get_plan and get_apply. List methods return next_cursor. Pass it back as cursor until it is None. The SDK Reference lists every method and its parameters.
Methods
| Method | Resource | Access |
|---|---|---|
list_organizations | Organizations | Read |
get_organization | Organizations | Read |
list_workspaces | Workspaces | Read |
get_workspace | Workspaces | Read |
create_workspace | Workspaces | Write |
update_workspace | Workspaces | Write |
list_workspace_variables | Workspace variables | Read |
create_workspace_variable | Workspace variables | Write |
update_workspace_variable | Workspace variables | Write |
list_variable_sets | Variable sets | Read |
create_variable_set | Variable sets | Write |
create_variable_set_variable | Variable sets | Write |
list_runs | Runs | Read |
get_run | Runs | Read |
create_run | Runs | Write |
get_plan | Plans | Read |
get_apply | Applies | Read |
list_configuration_versions | Configuration versions | Read |
create_configuration_version | Configuration versions | Write |
list_state_versions | State versions | Read |
get_current_state_version | State versions | Read |
list_state_version_outputs | State version outputs | Read |
list_projects | Projects | Read |
create_project | Projects | Write |
list_notification_configurations | Notification configurations | Read |
Details that affect results
create_runqueues a plan and always sends auto-apply as false, so the run waits for a person to confirm it in HCP Terraform even on a workspace with auto-apply on.plan_only=Truequeues a plan that can never apply. Destroy runs cannot be requested, andupdate_workspacecannot turn auto-apply on.create_runandcreate_configuration_versionneed a user or team token. An organization token gets a 403.create_configuration_versionreturns anupload_urlonly in that response. This connector does not upload the configuration archive. The version is always created withauto_queue_runsset toFalse, so uploading it never starts a run. Usecreate_runto plan it.- The value of a sensitive variable or sensitive output is
Nonein every read. A sensitive variable is write-only once saved. list_notification_configurationsshows only the host of each webhook URL and leaves out the token.list_state_versionsneeds bothorganizationandworkspace_name. The state version upload URLs are left out of the results.- A 404 can mean the token's user or team lacks permission to see the resource, because HCP Terraform hides what a token cannot read.
- A 401 marks the credential as needing a new token. A 403 does not, and its message points to the token type, its expiration date and its permissions.
- Saving a token checks it against the organizations list. A 403 or 404 there still lets the token save, because an organization token cannot list organizations. Only a 401 rejects it.
list_workspace_variablesreturns every variable in one response and has no paging.