From b63b07b50c7a9e1a62b34cec55907b6f501e31f6 Mon Sep 17 00:00:00 2001 From: Glenn Sarti Date: Wed, 11 Jun 2025 09:54:10 +0800 Subject: [PATCH 1/6] Fix table whitespace in run-tasks document This commit just updates the table whitespace in the markdown file. No change to docs rendering. --- .../run-tasks/run-tasks-integration.mdx | 96 +++++++++---------- 1 file changed, 48 insertions(+), 48 deletions(-) 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..dbbfc76a8 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,10 +127,10 @@ 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 @@ -157,13 +157,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 +189,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 From 33e565ecd9b58128fc7b90bbe657d1ba5a6ffb59 Mon Sep 17 00:00:00 2001 From: Glenn Sarti Date: Wed, 11 Jun 2025 10:08:09 +0800 Subject: [PATCH 2/6] Update run task timeout explanation The Run Task timeout behaviour has now changed from a fixed 10 minutes to "No progress update in the last 10 minutes, to a maximum runtime of 60 minutes" This commit updates the TFC docs to reflect this. --- .../cloud-docs/api-docs/run-tasks/run-tasks-integration.mdx | 6 ++++-- .../docs/cloud-docs/integrations/run-tasks/index.mdx | 3 ++- 2 files changed, 6 insertions(+), 3 deletions(-) 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 dbbfc76a8..3e7775f27 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 @@ -135,10 +135,12 @@ 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 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. +-> **Note:** HCP Terraform will consider the request as errored if it has not received a progress update in the last 10 minutes, or the request has been running for over 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` 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..9bf2ab15e 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`. +HCP Terraform will consider the request as errored if it has not received a progress callback in the last 10 minutes, or the task has been running for over 60 minutes. +The supplied message attribute will be displayed in HCP Terraform on the run details page. The status can be `running`, `passed` or `failed`. Here's what the data flow looks like: From 445ef6cc94a03e937bca418050bad475a4ddc948 Mon Sep 17 00:00:00 2001 From: Glenn Sarti Date: Thu, 12 Jun 2025 09:20:46 +0800 Subject: [PATCH 3/6] Update content/terraform-docs-common/docs/cloud-docs/integrations/run-tasks/index.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/cloud-docs/integrations/run-tasks/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 9bf2ab15e..57051bc4a 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 @@ -78,7 +78,7 @@ Once your server receives this payload, HCP Terraform expects you to callback to ``` HCP Terraform will consider the request as errored if it has not received a progress callback in the last 10 minutes, or the task has been running for over 60 minutes. -The supplied message attribute will be displayed in HCP Terraform on the run details page. The status can be `running`, `passed` or `failed`. +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: From ee21e5f7e6be35fd12580e467c87574d3caadbe2 Mon Sep 17 00:00:00 2001 From: Glenn Sarti Date: Thu, 12 Jun 2025 09:23:23 +0800 Subject: [PATCH 4/6] Update content/terraform-docs-common/docs/cloud-docs/api-docs/run-tasks/run-tasks-integration.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../cloud-docs/api-docs/run-tasks/run-tasks-integration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 3e7775f27..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 @@ -138,7 +138,7 @@ The POST request submits the following properties as the request headers. 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. --> **Note:** HCP Terraform will consider the request as errored if it has not received a progress update in the last 10 minutes, or the request has been running for over 60 minutes. +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`. From a2f68f218836b80d0662bcda19dcd42a565d96f0 Mon Sep 17 00:00:00 2001 From: Glenn Sarti Date: Thu, 12 Jun 2025 09:23:33 +0800 Subject: [PATCH 5/6] Update content/terraform-docs-common/docs/cloud-docs/integrations/run-tasks/index.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/cloud-docs/integrations/run-tasks/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 57051bc4a..93d8e4190 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,7 @@ Once your server receives this payload, HCP Terraform expects you to callback to } ``` -HCP Terraform will consider the request as errored if it has not received a progress callback in the last 10 minutes, or the task has been running for over 60 minutes. +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: From f55551e98ff6924c79703bcfa577681f12cb6d84 Mon Sep 17 00:00:00 2001 From: Glenn Sarti Date: Fri, 13 Jun 2025 09:39:15 +0800 Subject: [PATCH 6/6] Update Link to Packer Run Task --- .../docs/cloud-docs/integrations/run-tasks/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 93d8e4190..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 @@ -105,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.