Type '/' to Search

»Run Tasks Integration API

Note: Run Tasks is a paid feature, available as part of the Team & Governance upgrade package. Refer to Terraform Cloud pricing for details.

Run tasks allow Terraform Cloud to interact with external systems at specific points in the Terraform Cloud run lifecycle. This page lists the API endpoints used to trigger a run task and the expected response from the integration.

Refer to run tasks for the API endpoints to create and manage run tasks within Terraform Cloud.

»Run Task Request

When a run reaches the appropriate phase and a run task is triggered, Terraform Cloud will send a request to the run task's URL. The service receiving the run task request should respond with 200 OK, or Terraform Cloud will retry to trigger the run task.

POST :url

ParameterDescription
:urlThe URL configured in the run task to send requests to.
StatusResponseReason
200NothingSuccessfully submitted a run task

»Request Body

The POST request submits a JSON object with the following properties as a request payload.

Key pathTypeValuesDescription
payload_versioninteger1Schema version of the payload. Only 1 is supported.
access_tokenstringBearer token to use when calling back to Terraform Cloud.
stagestringpost-plan, pre-applyThe stage the task was triggered at.
is_speculativeboolWhether the task is part of a speculative run.
task_result_idstringID of task result within Terraform Cloud.
task_result_enforcement_levelstringmandatory, advisoryEnforcement level for this task.
task_result_callback_urlstringURL that should called back with the result of this task.
run_idstringId of the run this task is part of.
run_app_urlstringURL within Terraform Cloud to the run.
run_messagestringMessage that was associated with the run.
run_created_atstringWhen the run was started.
run_created_bystringWho created the run.
workspace_idstringId of the workspace the task is associated with.
workspace_namestringName of the workspace.
workspace_app_urlstringURL within Terraform Cloud to the workspace.
organization_namestringName of the organization the task is configured within.
plan_json_api_urlstringURL to retrieve the JSON Terraform plan for this run.
vcs_repo_urlstringURL to the workspace's VCS repository. This is null if the workspace does not have a VCS repository.
vcs_branchstringRepository branch that the workspace executes from. This is null if the workspace does not have a VCS repository.
vcs_pull_request_urlstringURL to the Pull Request/Merge Request that triggered this run. This is null if the run was not triggered.
vcs_commit_urlstringURL to the commit that triggered this run. This is null if the workspace does not a VCS repository.

»Sample Payload

{
  "payload_version": 1,
  "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q",
  "stage": "post_plan",
  "is_speculative": false,
  "task_result_id": "taskrs-2nH5dncYoXaMVQmJ",
  "task_result_enforcement_level": "mandatory",
  "task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback",
  "run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ",
  "run_id": "run-i3Df5to9ELvibKpQ",
  "run_message": "Triggered via UI",
  "run_created_at": "2021-09-02T14:47:13.036Z",
  "run_created_by": "username",
  "workspace_id": "ws-ck4G5bb1Yei5szRh",
  "workspace_name": "tfr_github_0",
  "workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace",
  "organization_name": "hashicorp",
  "plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output",
  "vcs_repo_url": "https://github.com/hashicorp/terraform-random",
  "vcs_branch": "main",
  "vcs_pull_request_url": null,
  "vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22"
}

{
  "payload_version": 1,
  "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q",
  "stage": "post_plan",
  "is_speculative": false,
  "task_result_id": "taskrs-2nH5dncYoXaMVQmJ",
  "task_result_enforcement_level": "mandatory",
  "task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback",
  "run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ",
  "run_id": "run-i3Df5to9ELvibKpQ",
  "run_message": "Triggered via UI",
  "run_created_at": "2021-09-02T14:47:13.036Z",
  "run_created_by": "username",
  "workspace_id": "ws-ck4G5bb1Yei5szRh",
  "workspace_name": "tfr_github_0",
  "workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace",
  "organization_name": "hashicorp",
  "plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output",
  "vcs_repo_url": "https://github.com/hashicorp/terraform-random",
  "vcs_branch": "main",
  "vcs_pull_request_url": null,
  "vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22"
}

»Request Headers

The POST request submits the following properties as the request headers.

NameValueDescription
Content-Typeapplication/jsonSpecifies the type of data in the request body
User-AgentTFC/1.0 (+https://app.terraform.io; TFC)Identifies the request is coming from Terraform Cloud
X-TFC-Task-SignaturestringIf the run task is configured with an HMAC Key, this header contains the signed SHA512 sum of the request payload using the configured HMAC key. Otherwise, this is an empty string.

»Run Task Callback

Once a run task request has been fulfilled by the external integration, the integration must call back into Terraform Cloud with the result. Terraform expects this callback within 10 minutes, or the request will be considered to have errored.

PATCH :callback_url

ParameterDescription
:callback_urlThe task_result_callback_url specified in the run task request. Typically /task-results/:guid/callback.
StatusResponseReason
200NothingSuccessfully submitted a run task result
401JSON API error objectNot authorized to perform action
[422][]JSON API error objectInvalid response payload. This could be caused by invalid attributes, or sending a status that is not accepted.

»Request Body

The PATCH request submits a JSON object with the following properties as a request payload.

Key pathTypeDescription
data.typestringMust be "task-results".
data.attributes.statusstringThe current status of the task. Only passed, failed or running are allowed.
data.attributes.messagestring(Optional) A short message describing the status of the task.
data.attributes.urlstring(Optional) A URL where users can obtain more information about the task.

Status values other than passed, failed, or running return an error. Both the passed and failed statuses represent a final state for a run task. The running status allows one or more partial updates until the task has reached a final state.

{
  "data": {
    "type": "task-results",
    "attributes": {
      "status": "passed",
      "message": "4 passed, 0 skipped, 0 failed",
      "url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ"
    }
  }
}

{
  "data": {
    "type": "task-results",
    "attributes": {
      "status": "passed",
      "message": "4 passed, 0 skipped, 0 failed",
      "url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ"
    }
  }
}

»Request Headers

The PATCH request must use the token supplied in the originating request (access_token) for authentication.