Update documentation and changelog

This commit updates the documentation and changelog for the Global Run
Tasks feature.

Author: glennsarti

CHANGELOG.md

@@ -4,6 +4,12 @@ FEATURES:
 * `r/tfe_team`: Add attribute `manage_agent_pools` to `organization_access` on `tfe_team` by @emlanctot [#1358](https://github.com/hashicorp/terraform-provider-tfe/pull/1358)
 * `r/tfe_workspace`: Add an `auto_destroy_activity_duration` attribute for automatic scheduling of auto-destroy runs based off of workspace activity, by @notchairmk [#1377](https://github.com/hashicorp/terraform-provider-tfe/pull/1377)
 * `d/tfe_workspace`: Add an `auto_destroy_activity_duration`, by @notchairmk [#1377](https://github.com/hashicorp/terraform-provider-tfe/pull/1377)
+* `d/tfe_organization_run_task_global_settings`: Add a datasource to retrieve the global settings of Run tasks, by @glennsarti [#1328](https://github.com/hashicorp/terraform-provider-tfe/pull/1330)
+* `r/tfe_organization_run_task_global_settings`: Add a resource to manage the global settings of Run tasks, by @glennsarti [#1328](https://github.com/hashicorp/terraform-provider-tfe/pull/1330)
+
+DEPRECATIONS and BREAKING CHANGES:
+* `r/_workspace_run_task`: The `stage` attribute has been deprecated in favor of the `stages` attribute, by @glennsarti [#1328](https://github.com/hashicorp/terraform-provider-tfe/pull/1330)
+* `d/_workspace_run_task`: The `stage` attribute has been deprecated in favor of the `stages` attribute, by @glennsarti [#1328](https://github.com/hashicorp/terraform-provider-tfe/pull/1330)
 
 ## v0.56.0
 

website/docs/d/organization_run_task_global_settings.html.markdown

@@ -0,0 +1,34 @@
+---
+layout: "tfe"
+page_title: "Terraform Enterprise: tfe_organization_run_task_global_settings"
+description: |-
+  Get information on a Run task's global settings.
+---
+
+# Data Source: tfe_organization_run_task_global_settings
+
+[Run tasks](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks) allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. Run tasks are reusable configurations that you can attach to any workspace in an organization.
+
+The tfe_organization_run_task_global_settings resource creates, updates and destroys the [global settings](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks#global-run-tasks) for an [Organization Run task](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks#creating-a-run-task). Your organization must have the `global-run-task` [entitlement](https://developer.hashicorp.com/terraform/cloud-docs/api-docs#feature-entitlements) to use global run tasks.
+
+## Example Usage
+
+```hcl
+data "tfe_organization_run_task_global_settings" "example" {
+  task_id = "task-abc123"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `task_id` - (Required) The id of the Run task with the global settings.
+
+## Attributes Reference
+
+In addition to all arguments above, the following attributes are exported:
+
+* `enabled` - Whether the run task will be applied globally.
+* `enforcement_level` - The enforcement level of the global task. Valid values are `advisory` and `mandatory`.
+* `stages` - The stages to run the task in. Valid values are one or more of `pre_plan`, `post_plan`, `pre_apply` and `post apply`.

website/docs/d/workspace_run_task.html.markdown

@@ -33,4 +33,5 @@ In addition to all arguments above, the following attributes are exported:
 
 * `enforcement_level` - The enforcement level of the task.
 * `id` - The ID of the Workspace Run task.
-* `stage` - Which stage the task will run in.
+* `stage` - **Deprecated** Use `stages` instead.
+* `stages` - Which stages the task will run in.

website/docs/r/organization_run_task_global_settings.html.markdown

@@ -0,0 +1,55 @@
+---
+layout: "tfe"
+page_title: "Terraform Enterprise: tfe_organization_run_task_global_settings"
+description: |-
+  Manages Run tasks global settings.
+---
+
+# tfe_organization_run_task_global_settings
+
+[Run tasks](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks) allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. Run tasks are reusable configurations that you can attach to any workspace in an organization.
+
+The tfe_organization_run_task_global_settings resource creates, updates and destroys the [global settings](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks#global-run-tasks) for an [Organization Run task](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks#creating-a-run-task). Your organization must have the `global-run-task` [entitlement](https://developer.hashicorp.com/terraform/cloud-docs/api-docs#feature-entitlements) to use global run tasks.
+
+## Example Usage
+
+Basic usage:
+
+```hcl
+resource "tfe_organization_run_task_global_settings" "example" {
+  task_id = tfe_organization_run_task.example.id
+  enabled           = true
+  enforcement_level = "advisory"
+  stages            = ["pre_plan", "post_plan"]
+}
+
+resource "tfe_organization_run_task" "example" {
+  organization = "org-name"
+  url          = "https://external.service.com"
+  name         = "task-name"
+  enabled      = true
+  description  = "An example task"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `enabled` - (Optional) Whether the run task will be applied globally.
+* `enforcement_level` - (Required) The enforcement level of the global task. Valid values are `advisory` and `mandatory`.
+* `stages` - (Required) The stages to run the task in. Valid values are one or more of `pre_plan`, `post_plan`, `pre_apply` and `post apply`.
+* `task_id` - (Required) The id of the Run task which will have the global settings applied.
+
+## Attributes Reference
+
+* `id` - The ID of the global settings.
+
+## Import
+
+Run task global settings can be imported; use `<ORGANIZATION NAME>/<TASK NAME>` as the
+import ID. For example:
+
+```shell
+terraform import tfe_organization_run_task_global_settings.test my-org-name/task-name
+```

website/docs/r/workspace_run_task.html.markdown

@@ -20,6 +20,7 @@ resource "tfe_workspace_run_task" "example" {
   workspace_id      = resource.tfe_workspace.example.id
   task_id           = resource.tfe_organization_run_task.example.id
   enforcement_level = "advisory"
+  stages = ["pre_plan"]
 }
 ```
 
@@ -30,7 +31,8 @@ The following arguments are supported:
 * `enforcement_level` - (Required) The enforcement level of the task. Valid values are `advisory` and `mandatory`.
 * `task_id` - (Required) The id of the Run task to associate to the Workspace.
 * `workspace_id` - (Required) The id of the workspace to associate the Run task to.
-* `stage` - (Optional) The stage to run the task in. Valid values are `pre_plan`, `post_plan`, and `pre_apply`.
+* `stage` - **Deprecated** Use `stages` instead.
+* `stages` - (Optional) The stages to run the task in. Valid values are one or more of `pre_plan`, `post_plan`, `pre_apply` and `post apply`.
 
 ## Attributes Reference