Run tasks integration API

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.

Run Task Request

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

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`, `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.

Key path	Type	Values	Description
`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"
}

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 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.

Run Task Callback

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

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.

{
  "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": [...]
      }
    }
  }
}

Outcomes Payload Body

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	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. 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"
  }
}

Complete Callback Payload Example

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"
            }
          }
        ]
      }
    }
  }
}

Request Headers

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