HCP Terraform run tasks represent a direct integration point between the Terraform run lifecycle and external systems that can inspect, validate, or act on Terraform configuration and execution data at precise moments. Each run task bound to a workspace transmits run data to an external service at a defined run stage. The external service processes the data and returns a passed or failed status to HCP Terraform. The platform then evaluates the enforcement level attached to the task and decides whether the run may continue toward provisioning infrastructure. This mechanism allows organizations to embed security scanning, compliance checks, policy validation, and custom notifications inside the normal Terraform workflow without modifying Terraform code.
The practical impact for operators is that governance moves from a post-deployment audit to an in-pipeline gate. A security vulnerability discovered in configuration can block an apply before resources are created, reducing remediation cost and risk exposure. For developers the integration preserves existing workflows while inserting automated checks. For platform teams the model offers a reusable way to standardize controls across many workspaces with a single external service endpoint.
The run task model is supported in HCP Terraform and can be adapted for Terraform Enterprise. Concepts, payload shapes, and lifecycle hooks remain consistent across both platforms, with UI and management paths differing only by product surface.
Core Mechanics of Run Tasks
Run tasks are custom HTTP services that HCP Terraform or Terraform Enterprise can call during specific stages of a Terraform run. They enable integration of custom validation, compliance checks, notifications, or any other logic into the Terraform workflow.
Each run task in a workspace sends run data to an external service at a specific run stage. The external service processes the data and returns a passed or failed status to HCP Terraform. For example, a run task can check configuration for any security vulnerabilities before Terraform applies that plan.
Run tasks send data about a run to an external service at specific run stages. The external service processes the data, evaluates whether the run passes or fails, and sends a response to HCP Terraform. HCP Terraform then uses this response and the run task enforcement level to determine if a run can proceed.
Run tasks send an API payload to an external service. The API payload contains run-related information, including a callback URL, which the service uses to return a pass or fail status to HCP Terraform.
The beta release of this feature allows users to add and execute these tasks during the new pre-apply stage which exists in between the plan and apply stages. Tasks are executed by sending an API payload to the external system. This payload contains a collection of run-related information and a callback URL which the external system can use to send updates back to Terraform Cloud.
The external system can then use this run information and respond back to Terraform Cloud with a passed or failed status. Terraform Cloud uses this status response to determine if a run should proceed, based on the task's enforcement settings within a workspace.
Run Lifecycle Stages and Interaction Points
Run tasks interact with Terraform runs at specific points in the lifecycle, e.g., post-plan and pre-apply.
A learning sandbox implementation covers all four stages: pre-plan, post-plan, pre-apply, and post-apply.
The pre-apply stage exists in between the plan and apply stages. This placement allows validation to occur after plan generation and before any infrastructure changes are made.
The ability to listen at each lifecycle stage provides full visibility into what Terraform exposes along the way. A flight recorder style task can fetch and save config files, plans, logs, and run metadata in a tidy folder layout without enforcing policy or blocking runs.
| Stage | Typical Use |
|---|---|
| pre-plan | Capture initial configuration before planning begins |
| post-plan | Analyze execution plan for drift, cost, or security issues |
| pre-apply | Final gate before changes are applied |
| post-apply | Capture outcomes and audit artifacts after apply completes |
The stage selection determines what data is available to the external service and what actions can be safely taken without disrupting the run.
Enforcement Levels and Run Outcome Logic
Run tasks have an enforcement level of advisory or mandatory set within the Terraform workspace.
The Terraform run will stop the deployment if the Run Task returns a failed status, and the enforcement level is set to mandatory.
Depending on the enforcement level, failed run tasks can stop runs and prevent Terraform from provisioning infrastructure. For example, a run fails if a mandatory task fails, even if an advisory task succeeds. If an advisory task fails, but a mandatory task succeeds, the run succeeds and proceeds to the apply stage, where it can provision infrastructure.
This logic creates a layered guardrail model. Mandatory tasks act as hard gates. Advisory tasks provide visibility and reporting without blocking delivery, allowing teams to build confidence before promoting checks to mandatory.
| Enforcement Level | Failure Behavior | Run Proceeds |
|---|---|---|
| mandatory | Run stops and deployment is prevented | Only if status is passed |
| advisory | Run continues with warning | Even if status is failed, provided mandatory tasks pass |
The choice of enforcement level is made per task within the workspace and directly shapes risk tolerance for the organization.
Terraform Version Requirements and Downgrade Behavior
Run tasks can only be created on workspaces using a Terraform version v0.12+. Downgrading a workspace with existing run tasks to use a Terraform version v0.12 or prior will not result in an error, but the configured tasks will not execute.
You can assign run tasks to workspaces that use a Terraform version of 1.1.9 and later. You can downgrade a workspace with existing runs to use a prior Terraform version without causing an error. However, HCP Terraform no longer triggers the run tasks during plan and apply operations.
The version requirement ensures the workspace can understand the run task payload schema and lifecycle hooks introduced in modern Terraform. Downgrade behavior is non-destructive: the association remains in configuration, but execution is suppressed to avoid breaking older Terraform binaries that cannot process the callbacks.
This behavior has operational impact when teams experiment with older modules or self-managed Terraform versions. Platform operators should track workspace Terraform version settings as part of change management for run task rollout.
| Requirement Source | Minimum Terraform Version | Notes |
|---|---|---|
| Beta documentation | v0.12+ | Tasks will not execute if downgraded to v0.12 or prior |
| Current documentation | 1.1.9 and later | Downgrade suppresses triggers without error |
Permissions and Access Control
Permissions control who can create run tasks and associate them with workspaces.
To create a run task, you must have a user account with the Manage Run Tasks permission.
To associate run tasks with a workspace, you need the Manage Workspace Run Tasks permission on that particular workspace.
You must be an organization owner to create a new task event hook.
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.
The permission model separates creation of the reusable task definition from its binding to a specific workspace. This separation supports central governance teams creating approved tasks and delegating workspace-level assignment to team owners.
| Permission | Scope |
|---|---|
| Manage Run Tasks | Create run task definitions at organization level |
| Manage Workspace Run Tasks | Associate existing tasks with a workspace |
| Organization Owner | Create task event hooks |
Creating and Managing Run Tasks
You can manage run tasks through the HCP Terraform UI or the Run Tasks API.
To create a new run task:
- Sign in to HCP Terraform or Terraform Enterprise and navigate to the workspace where you want to create a run task.
- Navigate to Organization Settings and select Run Tasks.
- Click Create a new run task. The Run Tasks page appears.
- Enter the information about the run task to be configured:
- Enabled (optional): Whether the run task will run across all associated workspaces. New tasks are enabled by default.
- Name (required): A human-readable name for the run task
The Enabled flag controls whether the task definition is active across all associated workspaces. New tasks are enabled by default, which means immediate execution once bound to a workspace.
Management via the UI or API provides parity for automation. Teams that codify governance often use the Run Tasks API to version task definitions alongside other policy artifacts.
Registry, Partner Program and Reuse
Browse a list of all run tasks in the Terraform Registry or use keywords to search for run tasks relevant to your use cases.
Click a run task to view its documentation on our partner’s site.
Adding a run task to the Terraform registry makes your run task available for other consumers and HashiCorp partners.
To add your run task to the Terraform registry:
- Complete the Technology Program Application.
- Sign our Technology Partner Agreement to become a HashiCorp technology partner. HashiCorp sends you the agreement after you complete Technology Program Application.
- Build and test your run task
Registry publication turns an internal validation service into a discoverable asset. For vendors, it provides distribution. For consumers, it reduces build time for common checks such as security scanning and compliance validation.
Explore run tasks in the Terraform registry. The full list of run tasks is discoverable through the Terraform Registry.
API Payload and Callback Flow
Run tasks send an API payload to an external service. The API payload contains run-related information, including a callback URL, which the service uses to return a pass or fail status to HCP Terraform.
The external service processes the data and returns a passed or failed status to HCP Terraform. For example, you could add a run task that checks configuration for any security vulnerabilities before Terraform applies that plan.
The callback mechanism decouples execution time from Terraform. The external service can perform long-running analysis and report back asynchronously, with HCP Terraform polling or awaiting the callback before proceeding.
Hands-on: Try the HCP Packer validation run task tutorial. For example, the HCP Packer integration checks image artifacts within a Terraform configuration for validity. If the configuration references images marked as unusable (revoked), then the run task fails and provides an error message.
Practical Integration Examples
The Wiz integration with Terraform Cloud and Terraform Enterprise is a post-plan or pre-apply run task that scans the user’s IaC Terraform configuration and detects secrets and misconfigurations. This integration helps to automate and enforce security best practices, ensuring that only secure infrastructure is deployed — thereby reducing the organization's overall risk exposure.
The benefits of this integration include:
- Early and consistent reduction of risk: Wiz enables you to take runtime security learnings and apply them (in the form of security scans and policies) into the pipeline enabling a consistent security approach.
- Improved efficiency: Enable developers and cloud teams to be productive by integrating their security checks into their existing workflow resulting in faster remediation.
- Wiz's Run Tasks integration serves as a security guardrail, scanning for predefined security policies and preventing insecure deployments
Use run tasks to validate Terraform configuration files, analyze execution plans before applying them, scan for security vulnerabilities, or perform other custom actions.
Learning Sandbox and Implementation Patterns
A hands-on, low-stakes way to learn Terraform Run Tasks is a sandbox repository that builds a small, playful Run Task that doesn’t enforce policy or block runs. It listens at each lifecycle stage and captures useful artifacts and API responses so you can explore exactly what Terraform exposes along the way.
Think of it as a flight recorder for your runs—not an air-traffic controller. It fetches and saves config files, plans, logs, and run metadata in a tidy folder layout.
Use it to learn the Run Task workflow end-to-end or as a starting point for your own tasks. It covers all four stages: pre-plan, post-plan, pre-apply, and post-apply.
Once you have a handle on the approach, be sure to take a look at the Displaying Run Task Results doc to see how to customize the Run Task response and display results in the UI.
This documentation focuses on HCP Terraform, but the concepts and code can be adapted for Terraform Enterprise as well.
The repository is organized to provide a clear separation between the run task implementation, helper utilities, and infrastructure setup.
main.go
- Entry point of the application
The beauty of run tasks is that you have access to the full Terraform context and can make decisions or take actions at the perfect moment in the workflow.
Troubleshooting, Health Checks and Operational Readiness
HCP Terraform will perform a health check on the run task URL when creating the association and if it cannot reach the URL, the creation will fail.
If the hcp-terraform/setup Terraform fails during apply creating the run task, be sure that the webserver and tunnel are running and accessible.
Operational verification steps include:
- Verify the tunnel is running and accessible via
task healthcheck - Check that the workspace is properly associated with the run task
- Ensure the HMAC key matches between the server and HCP Terraform
- Verify your
TERRAFORM_API_TOKENenvironment variable is set correctly - Check that your token has sufficient permissions for the organization
- Ensure cloudflared is installed and working
- Check firewall settings if the tunnel can't start
Health check failures block creation to prevent silent misconfigurations. Matching HMAC keys ensures request integrity between HCP Terraform and the external service. Correct TERRAFORM_API_TOKEN values and organization permissions are required for API callbacks and metadata retrieval.
Beta Status and Availability Notes
Note: As of September 2021, Run Tasks are available only as a beta feature, are subject to change, and not all customers will see this functionality in their Terraform Cloud organization.
The beta note signals that feature availability and UI paths may evolve. Organizations adopting run tasks should monitor product release notes for changes to lifecycle stages, payload schemas, and permission models.
Conclusion
Terraform run tasks embed external validation and automation directly into the Terraform run lifecycle, shifting security and compliance left to the plan and pre-apply phases. The model relies on precise stage selection, clear enforcement semantics, and a callback-based status exchange to gate deployments without disrupting developer velocity. Version requirements, permission boundaries, and health checks create operational guardrails for safe adoption. Registry publication and partner programs accelerate reuse, while sandbox implementations provide low-risk learning paths. As organizations mature their platform, mandatory tasks become enforceable policy gates and advisory tasks provide continuous visibility, together reducing risk exposure while preserving delivery speed.