diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/run-tasks/run-tasks-integration.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/run-tasks/run-tasks-integration.mdx index 0e1aa877a..0fc8ee215 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/run-tasks/run-tasks-integration.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/run-tasks/run-tasks-integration.mdx @@ -53,33 +53,33 @@ The POST request submits a JSON object with the following properties as a reques 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](/terraform/cloud-docs/run/states) 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](/terraform/cloud-docs/api-docs/configuration-versions#download-configuration-files). This is `null` if the configuration version is not available to download. | -| `configuration_version_id` | string | | The ID of the [configuration version](/terraform/cloud-docs/api-docs/configuration-versions) for the run. | -| `is_speculative` | bool | | Whether the task is part of a [speculative run](/terraform/cloud-docs/run/remote-operations#speculative-plans). | -| `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](/terraform/cloud-docs/workspaces/settings#terraform-working-directory). | +| 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](/terraform/cloud-docs/run/states) 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](/terraform/cloud-docs/api-docs/configuration-versions#download-configuration-files). This is `null` if the configuration version is not available to download. | +| `configuration_version_id` | string | | The ID of the [configuration version](/terraform/cloud-docs/api-docs/configuration-versions) for the run. | +| `is_speculative` | bool | | Whether the task is part of a [speculative run](/terraform/cloud-docs/run/remote-operations#speculative-plans). | +| `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](/terraform/cloud-docs/workspaces/settings#terraform-working-directory). | #### Post-Plan, Pre-Apply, and Post-Apply Properties @@ -127,18 +127,20 @@ Requests with `stage` set to `post_plan`, `pre_apply` or `post_apply` contain th 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 | +| 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](/terraform/cloud-docs/integrations/run-tasks#securing-your-run-task), 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 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. +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. -Once the external integration fulfills the request, that integration must call back into HCP Terraform with the overall result of either `passed` or `failed`. Terraform expects this callback within 10 minutes, or the request is considered errored. +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` @@ -157,13 +159,13 @@ You can send outcomes with a status of `running`, `passed`, or `failed`, but it 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](https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-result.json). -| 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. | +| 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. @@ -189,16 +191,16 @@ Status values other than passed, failed, or running return an error. Both the pa 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](#severity-and-status-tags) 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. | +| 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](#severity-and-status-tags) 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 diff --git a/content/terraform-docs-common/docs/cloud-docs/integrations/run-tasks/index.mdx b/content/terraform-docs-common/docs/cloud-docs/integrations/run-tasks/index.mdx index 52a32e1bc..e03165203 100644 --- a/content/terraform-docs-common/docs/cloud-docs/integrations/run-tasks/index.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/integrations/run-tasks/index.mdx @@ -77,7 +77,8 @@ Once your server receives this payload, HCP Terraform expects you to callback to } ``` -HCP Terraform expects this callback within 10 minutes, or the task will be considered to have `errored`. The supplied message attribute will be displayed in HCP Terraform on the run details page. The status can be `running`, `passed` or `failed`. +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. +HCP Terraform displays the supplied message attribute on the run details page. The status is either `running`, `passed`, or `failed`. Here's what the data flow looks like: @@ -104,4 +105,4 @@ $ echo -n $WEBHOOK_BODY | openssl dgst -sha512 -hmac "$HMAC_KEY" The HCP Packer validation run task checks the image artifacts within a Terraform configuration. If the configuration references images marked as unusable (revoked), the run task fails and provides an error message containing the number of revoked artifacts and whether HCP Packer has metadata for newer versions. For HCP Packer Plus registries, run tasks also help you identify hardcoded and untracked images that may not meet security and compliance requirements. -To get started, [create an HCP Packer account](https://cloud.hashicorp.com/products/packer) and follow the instructions in the [HCP Packer Run Task](/hcp/docs/packer/manage-image-use/terraform-cloud-run-tasks) documentation. +To get started, [create an HCP Packer account](https://cloud.hashicorp.com/products/packer) and follow the instructions in the [HCP Packer Run Task](/hcp/docs/packer/store/validate-version#set-up-the-hcp-terraform-run-task-for-hcp-packer) documentation.