Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. This page lists the API endpoints used to trigger a run task and the expected response from the integration.
Note: HCP Terraform Free edition includes one run task integration that you can apply to up to ten workspaces. Refer to HCP Terraform pricing for details.
Refer to run tasks for the API endpoints to create and manage run tasks within HCP Terraform. You can also access a complete list of all run tasks in the Terraform Registry.
When a run reaches the appropriate phase and a run task is triggered, HCP Terraform will send a request to the run task's URL.
Either HCP Terraform itself, or a self-hosted HCP Terraform agent using request forwarding can make the request to a run task's URL. Your organization must be entitled to private-run-tasks to use request forwarding.
The service receiving the run task request should respond with 200 OK, or HCP Terraform will retry to trigger the run task.
POST :url
: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 PropertiesAll request payloads contain the following properties.
Key path Type Values Descriptionpayload_version integer 1 Schema version of the payload. Only 1 is supported. stage string pre_plan, post_plan, pre_apply, post_apply The run stage when HCP Terraform triggers the run task. access_token string Bearer token to use when calling back to HCP Terraform. capabilities object A map of the capabilities that the caller supports. capabilities.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 HCP Terraform 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 HCP Terraform. 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 HCP Terraform 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, Pre-Apply, and Post-Apply Properties
Requests with stage set to post_plan, pre_apply or post_apply contain the following additional properties.
plan_json_api_url string The URL to retrieve the JSON Terraform plan for this run. Sample Payload
{
"payload_version": 1,
"stage": "post_plan",
"access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q",
"capabilities": {
"outcomes": true
},
"configuration_version_download_url": "https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download",
"configuration_version_id": "cv-ntv3HbhJqvFzamy7",
"is_speculative": false,
"organization_name": "hashicorp",
"plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output",
"run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ",
"run_created_at": "2021-09-02T14:47:13.036Z",
"run_created_by": "username",
"run_id": "run-i3Df5to9ELvibKpQ",
"run_message": "Triggered via UI",
"task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback",
"task_result_enforcement_level": "mandatory",
"task_result_id": "taskrs-2nH5dncYoXaMVQmJ",
"vcs_branch": "main",
"vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22",
"vcs_pull_request_url": null,
"vcs_repo_url": "https://github.com/hashicorp/terraform-random",
"workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace",
"workspace_id": "ws-ck4G5bb1Yei5szRh",
"workspace_name": "tfr_github_0",
"workspace_working_directory": "/terraform"
}
The POST request submits the following properties as the request headers.
Name Value DescriptionContent-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 HCP Terraform 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.
While a run task runs, it should send progressive updates to HCP Terraform 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.
The request errors if HCP Terraform does not receive a progress update within 10 minutes or if the request runs for more than 60 minutes.
Once the external integration fulfills the request, that integration must call back into HCP Terraform with the overall result of either passed or failed. 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
: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 schema for run task results.
Key path Type Descriptiondata.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.
{
"data": {
"type": "task-results",
"attributes": {
"status": "passed",
"message": "4 passed, 0 skipped, 0 failed",
"url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ"
},
"relationships": {
"outcomes": {
"data": [...]
}
}
}
}
A run task result may optionally contain one or more detailed outcomes, which improves result visibility and content in the HCP Terraform user interface. The following attributes define the outcome.
Key path Type Descriptionoutcome-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. We recommend limiting messages to under 1MB with a maximum allowable limit of 5MB. 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 HCP Terraform, enabling an earlier response to issues with severity and status.
{
"type": "task-result-outcomes",
"attributes": {
"outcome-id": "PRTNR-CC-TF-127",
"description": "ST-2942: S3 Bucket will not enforce MFA login on delete requests",
"tags": {
"Status": [
{
"label": "Denied",
"level": "error"
}
],
"Severity": [
{
"label": "High",
"level": "error"
},
{
"label": "Recoverable",
"level": "info"
}
],
"Cost Centre": [
{
"label": "IT-OPS"
}
]
},
"body": "# Resolution for issue ST-2942\n\n## Impact\n\nFollow instructions in the [AWS S3 docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiFactorAuthenticationDelete.html) to manually configure the MFA setting.\n—-- Payload truncated —--",
"url": "https://external.service.dev/result/PRTNR-CC-TF-127"
}
}
The example below shows a complete payload explaining the data structure of a callback payload, including all the necessary fields.
{
"data": {
"type": "task-results",
"attributes": {
"status": "failed",
"message": "0 passed, 0 skipped, 1 failed",
"url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ"
},
"relationships": {
"outcomes": {
"data": [
{
"type": "task-result-outcomes",
"attributes": {
"outcome-id": "PRTNR-CC-TF-127",
"description": "ST-2942: S3 Bucket will not enforce MFA login on delete requests",
"tags": {
"Status": [
{
"label": "Denied",
"level": "error"
}
],
"Severity": [
{
"label": "High",
"level": "error"
},
{
"label": "Recoverable",
"level": "info"
}
],
"Cost Centre": [
{
"label": "IT-OPS"
}
]
},
"body": "# Resolution for issue ST-2942\n\n## Impact\n\nFollow instructions in the [AWS S3 docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiFactorAuthenticationDelete.html) to manually configure the MFA setting.\n—-- Payload truncated —--",
"url": "https://external.service.dev/result/PRTNR-CC-TF-127"
}
}
]
}
}
}
}
The PATCH request must use the token supplied in the originating request (access_token) for authentication.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4