HashiConf Global Join us for HashiConf Global October 4-6 in Los Angeles & online. Register Now
  • Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHub
Download
Try Terraform Cloud

    Terraform Cloud

  • Overview
  • Plans and Features
  • Getting Started
    • API Docs template
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Assessment Results
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
      • Modules
      • Providers
      • Private Provider Versions and Platforms
      • GPG Keys
    • Runs
      • Run Tasks
      • Stages and Results
      • Custom Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Access
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Resources
    • Variable Sets
    • Changelog
    • Stability Policy
    • Overview
    • Creating Workspaces
    • Naming
    • Terraform Configurations
      • Overview
      • Managing Variables
      • Overview
      • VCS Connections
      • Access
      • Drift Detection
      • Notifications
      • SSH Keys for Modules
      • Run Triggers
      • Run Tasks
    • Terraform State
    • JSON Filtering
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
    • Users
    • Teams
    • Organizations
    • Permissions
    • Two-factor Authentication
    • API Tokens
      • Overview
      • Microsoft Azure AD
      • Okta
      • SAML
      • Linking a User Account
      • Testing
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
    • Overview
    • Adding Public Providers and Modules
    • Publishing Private Providers
    • Publishing Private Modules
    • Using Providers and Modules
    • Configuration Designer
  • Migrating to Terraform Cloud
    • Overview
    • Using Sentinel with Terraform 0.12
    • Manage Policies
    • Enforce and Override Policies
    • Mocking Terraform Sentinel Data
    • Working With JSON Result Data
      • Overview
      • tfconfig
      • tfconfig/v2
      • tfplan
      • tfplan/v2
      • tfstate
      • tfstate/v2
      • tfrun
    • Example Policies
    • Overview
    • AWS
    • GCP
    • Azure
      • Overview
      • Service Catalog
      • Admin Guide
      • Developer Reference
      • Example Customizations
      • V1 Setup Instructions
    • Splunk Integration
    • Kubernetes Integration
    • Run Tasks Integration
    • Overview
    • IP Ranges
    • Data Security
    • Security Model
    • Overview
    • Part 1: Overview of Our Recommended Workflow
    • Part 2: Evaluating Your Current Provisioning Practices
    • Part 3: How to Evolve Your Provisioning Practices
    • Part 3.1: From Manual Changes to Semi-Automation
    • Part 3.2: From Semi-Automation to Infrastructure as Code
    • Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
    • Part 3.4: Advanced Workflow Improvements

  • Terraform Cloud Agents

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Run Tasks

Note: Run Tasks is a paid feature, available as part of the Team & Governance upgrade package. Refer to Terraform Cloud pricing for details.

Run Tasks allow you to directly integrate third-party tools and services at certain stages in the Terraform Cloud run lifecycle. When triggered, a run task sends an API payload to the external service. This payload contains a collection of run-related information, including a callback URL that the service uses to 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 run task's enforcement settings that have been configured for the workspace.

You can manage run tasks through the UI or through the Run Tasks APIs.

Hands-on: Try the Configure Snyk Run Task in Terraform Cloud tutorial on HashiCorp Learn.

»Requirements

Terraform Version - You can only assign run tasks to workspaces that use a Terraform version of 0.12 and later. Downgrading a workspace with existing run tasks to use a prior Terraform version will not result in an error, but Terraform Cloud will no longer trigger the run tasks during plan and apply operations.

Permissions - 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.

»Creating a Run Task

Refer to Run Tasks Integration for a list of available run tasks. These include the HCP Packer integration and run tasks developed by HashiCorp Technology Partners.

To create a new run task:

  1. Navigate to the desired workspace, open the Settings menu, and select Run Tasks.

  2. Click Create a new run task. The Run Tasks page appears.

  3. 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. This will be displayed in workspace configuration pages and can contain letters, numbers, dashes and underscores.
    • Endpoint URL (required): The URL for the external service. Run tasks will POST the run tasks payload to this URL.
    • Description (optional): A human-readable description for the run task. This information can contain letters, numbers, spaces, and special characters.
    • HMAC key (optional): A secret key that may be required by the external service to verify request authenticity.
  4. Click Create run task. The run task is now available within the organization, and you can associate it with one or more workspaces.

»Associating Run Tasks with a Workspace

  1. Click Workspaces in the top navigation bar and then go to the workspace where you want to associate run tasks.

  2. Open the Settings menu and select Run Tasks.

  3. Click the + next to the task you want to add to the workspace.

  4. Choose when Terraform Cloud should start the run task:

Note: Pre-plan run tasks are in beta.

  • Pre-plan: Before Terraform creates the plan.
  • Post-plan: After Terraform creates the plan.
  1. Choose an enforcement level:

    • Advisory: Run tasks can not block a run from completing. If the task fails, the run will proceed with a warning in the UI.
    • Mandatory: Run tasks can block a run from completing. If the task fails (including a timeout or unexpected remote error condition), the run will transition to an Errored state with a warning in the UI.
  2. Click Create. Your run task is now configured.

»Understanding Run Tasks Within a Run

Run tasks perform actions between the plan and apply stages of a Terraform run. Once all run tasks have completed, the run will end based on the most restrictive enforcement level in each associated run task.

For example, if a mandatory task fails and an advisory task succeeds, the run will fail. If an advisory task fails, but a mandatory task succeeds, the run will succeed and proceed to the apply stage. Regardless of the exit status of a task, Terraform Cloud displays the status and any related message data in the UI.

The following example shows a run that failed due to a mandatory run task.

Screenshot: a run with failed tasks

The following example shows a run that succeeded.

Screenshot: a run with passed tasks

»Removing a Run Task from a Workspace

Removing a run task from a workspace does not delete it from the organization. To remove a run task from a specific workspace:

  1. Navigate to the desired workspace, open the Settings menu and select Run Tasks.

  2. Click the ellipses (...) on the associated run task, and then click Remove. The run task will no longer be applied to runs within the workspace.

»Deleting a Run Task

You must remove a run task from all associated workspaces before you can delete it. To delete a run task:

  1. Navigate to Settings in the top navigation bar and click Run Tasks.

  2. Click the ellipses (...) next to the run task you want to delete, and then click Edit.

  3. Click Delete run task.

You cannot delete run tasks that are still associated with a workspace. If you attempt this, you will see a warning in the UI containing a list of all workspaces that are associated with the run task.

github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager