Skip to main content

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​

  1. 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.
  2. 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.
  3. Open Account settings, then Tokens, and click Create an API token.
  4. Choose a short expiration, such as 30 days.
  5. Copy the token. HCP Terraform shows it once, so paste it straight into qbash or keep it somewhere safe.
  6. Confirm the token can write. In the organization, create a test workspace in the HCP Terraform UI, or run create_project from 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.

TokenPermissionsNotes
UserThe permissions of the user who made itThe practical choice on the Free plan, which has no teams
TeamThe access of the team on its workspacesNeeds a paid plan. A team token can start runs and create configuration versions
OrganizationCan create and configure workspaces and teamsCannot 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​

  1. Open Connectors, then Terraform, and click Connect.
  2. Fill in Credential Name, such as "qbash platform workspaces", and paste the token into API Token.
  3. Save. qbash checks the token with HCP Terraform and saves it only if HCP Terraform accepts it.
  4. 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​

MethodResourceAccess
list_organizationsOrganizationsRead
get_organizationOrganizationsRead
list_workspacesWorkspacesRead
get_workspaceWorkspacesRead
create_workspaceWorkspacesWrite
update_workspaceWorkspacesWrite
list_workspace_variablesWorkspace variablesRead
create_workspace_variableWorkspace variablesWrite
update_workspace_variableWorkspace variablesWrite
list_variable_setsVariable setsRead
create_variable_setVariable setsWrite
create_variable_set_variableVariable setsWrite
list_runsRunsRead
get_runRunsRead
create_runRunsWrite
get_planPlansRead
get_applyAppliesRead
list_configuration_versionsConfiguration versionsRead
create_configuration_versionConfiguration versionsWrite
list_state_versionsState versionsRead
get_current_state_versionState versionsRead
list_state_version_outputsState version outputsRead
list_projectsProjectsRead
create_projectProjectsWrite
list_notification_configurationsNotification configurationsRead

Details that affect results​

  • create_run queues 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=True queues a plan that can never apply. Destroy runs cannot be requested, and update_workspace cannot turn auto-apply on.
  • create_run and create_configuration_version need a user or team token. An organization token gets a 403.
  • create_configuration_version returns an upload_url only in that response. This connector does not upload the configuration archive. The version is always created with auto_queue_runs set to False, so uploading it never starts a run. Use create_run to plan it.
  • The value of a sensitive variable or sensitive output is None in every read. A sensitive variable is write-only once saved.
  • list_notification_configurations shows only the host of each webhook URL and leaves out the token.
  • list_state_versions needs both organization and workspace_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_variables returns every variable in one response and has no paging.