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

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.

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.

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.

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

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.

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 Terraform Cloud user interface. The following attributes define the outcome.

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.

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