Run Tasks Integration API
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. You can also access a complete list of all run tasks in the Terraform Registry.
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
Parameter | Description |
---|---|
:url | The URL configured in the run task to send requests to. |
Status | Response | Reason |
---|---|---|
200 | No Content | Successfully submitted a run task |
Request Body
The POST request submits a JSON object with the following properties as a request payload.
Common Properties
All request payloads contain the following properties.
Key path | Type | Values | Description |
---|---|---|---|
payload_version | integer | 1 | Schema version of the payload. Only 1 is supported. |
stage | string | pre_plan , post_plan , pre_apply | The run stage when Terraform Cloud triggers the run task. |
access_token | string | Bearer token to use when calling back to Terraform Cloud. | |
capabilitites | object | A map of the capabilities that the caller supports. | |
capabilitites.outcomes | bool | A flag indicating the caller accepts detailed run task outcomes. | |
configuration_version_download_url | string | The URL to download the configuration version. This is null if the configuration version is not available to download. | |
configuration_version_id | string | The ID of the configuration version for the run. | |
is_speculative | bool | Whether the task is part of a speculative run. | |
organization_name | string | Name of the organization the task is configured within. | |
run_app_url | string | URL within Terraform Cloud to the run. | |
run_created_at | string | When the run was started. | |
run_created_by | string | Who created the run. | |
run_id | string | Id of the run this task is part of. | |
run_message | string | Message that was associated with the run. | |
task_result_callback_url | string | URL that should called back with the result of this task. | |
task_result_enforcement_level | string | mandatory , advisory | Enforcement level for this task. |
task_result_id | string | ID of task result within Terraform Cloud. | |
vcs_branch | string | Repository branch that the workspace executes from. This is null if the workspace does not have a VCS repository. | |
vcs_commit_url | string | URL to the commit that triggered this run. This is null if the workspace does not a VCS repository. | |
vcs_pull_request_url | string | URL to the Pull Request/Merge Request that triggered this run. This is null if the run was not triggered. | |
vcs_repo_url | string | URL to the workspace's VCS repository. This is null if the workspace does not have a VCS repository. | |
workspace_app_url | string | URL within Terraform Cloud to the workspace. | |
workspace_id | string | Id of the workspace the task is associated with. | |
workspace_name | string | Name of the workspace. | |
workspace_working_directory | string | The working directory specified in the run's workspace settings. |
Post-Plan and Pre-Apply Properties
Requests with stage
set to post_plan
or pre_apply
contain the following additional properties.
Key path | Type | Values | Description |
---|---|---|---|
plan_json_api_url | string | The URL to retrieve the JSON Terraform plan for this run. |
Sample Payload
Request Headers
The POST request submits the following properties as the request headers.
Name | Value | Description |
---|---|---|
Content-Type | application/json | Specifies the type of data in the request body |
User-Agent | TFC/1.0 (+https://app.terraform.io; TFC) | Identifies the request is coming from Terraform Cloud |
X-TFC-Task-Signature | string | If 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
While a run task runs, it may send progressive updates to Terraform Cloud with a running
status. Once an integrator determines that Terraform supports detailed run task outcomes, they can send these outcomes by appending to the run task's callback payload.
Once the external integration fulfills the request, that integration must call back into Terraform Cloud with the overall result of either passed
or failed
. Terraform expects this callback within 10 minutes, or the request is considered errored.
You can send outcomes with a status of running
, passed
, or failed
, but it is a good practice only to send outcomes when a run task is running
.
PATCH :callback_url
Parameter | Description |
---|---|
:callback_url | The task_result_callback_url specified in the run task request. Typically /task-results/:guid/callback . |
Status | Response | Reason |
---|---|---|
200 | No Content | Successfully submitted a run task result |
401 | JSON API error object | Not authorized to perform action |
422 | JSON API error object | Invalid 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. This payload is also described in the JSON API schema for run task results.
Key path | Type | Description |
---|---|---|
data.type | string | Must be "task-results" . |
data.attributes.status | string | The current status of the task. Only passed , failed or running are allowed. |
data.attributes.message | string | (Recommended, but optional) A short message describing the status of the task. |
data.attributes.url | string | (Optional) A URL where users can obtain more information about the task. |
relationships.outcomes.data | array | (Recommended, but optional) A collection of detailed run task outcomes. |
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.
Outcomes Payload Body
A run task result may optionally contain one or more detailed outcomes, which improves result visibility and content in the Terraform Cloud user interface.
Key path | Type | Description |
---|---|---|
outcome-id | string | A partner supplied identifier for this outcome. |
description | string | A one-line description of the result. |
body | string | (Optional) A detailed message for the result in Markdown format. |
url | string | (Optional) A URL that a user can navigate to for more information about this result. |
tags | object | (Optional) An object containing tag arrays, named by the property key. |
tags.key | string | The two or three word name of the header tag. Special handling is given to severity and status keys. |
tags.key[].label | string | The text value of the tag. |
tags.key[].level | enum string | (Optional) The error level for the tag. Defaults to none , but accepts none , info , warning , or error . For levels other than none , labels render with a color and icon for that level. |
Severity and Status Tags
Run task outcomes with tags named "severity" or "status" are enriched within the outcomes display list in Terraform Cloud, enabling an earlier response to issues with severity and status.
Request Headers
The PATCH request must use the token supplied in the originating request (access_token
) for authentication.