terraform Each plan and apply run passes through several stages of action pending plan cost estimation policy check apply and completion HCP Terraform shows a run s progress through each stage as a run state policy check apply and complete Learn what happens during each stage of a run pending plan cost estimation page title Run States and Stages Runs HCP Terraform Run States and Stages

Answer:
---
page_title: Run States and Stages - Runs - HCP Terraform
description: >-
  Learn what happens during each stage of a run: pending, plan, cost estimation,
  policy check, apply, and complete.
---

# Run States and Stages

Each plan and apply run passes through several stages of action: pending, plan, cost estimation, policy check, apply, and completion. HCP Terraform shows a run's progress through each stage as a run state.

In the list of workspaces on HCP Terraform's main page, each workspace shows the state of the run it's currently processing. If no run is in progress, HCP Terraform displays the state of the most recently completed run.

## The Pending Stage

_States in this stage:_

- **Pending:** HCP Terraform hasn't started action on a run yet. HCP Terraform processes each workspace's runs in the order they were queued, and a run remains pending until every run before it has completed.

_Leaving this stage:_

- If the user discards the run before it starts, the run does not continue (**Discarded** state).
- If the run is first in the queue, it proceeds automatically to the plan stage (**Planning** state).

## The Fetching Stage

HCP Terraform may need to fetch the configuration from VCS prior to starting the plan. HCP Terraform automatically archives configuration versions created through VCS when all runs are complete and then re-fetches the files for subsequent runs.

_States in this stage:_

- **Fetching:** If HCP Terraform has not yet fetched the configuration from VCS, the run will go into this state until the configuration is available.

_Leaving this stage:_

- If HCP Terraform encounters an error when fetching the configuration from VCS, the run does not continue (**Plan Errored** state).
- If Terraform successfully fetches the configuration, the run moves to the next stage.

## The Pre-Plan Stage

The pre-plan phase only occurs if there are enabled [run tasks](/terraform/cloud-docs/workspaces/settings/run-tasks) in the workspace that are configured to begin before Terraform creates the plan. HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue. The information sent to the external system includes the configuration version of the run.

All runs can enter this phase, including [speculative plans](/terraform/cloud-docs/run/remote-operations#speculative-plans).

_States in this stage:_

- **Pre-plan running:** HCP Terraform is waiting for a response from the configured external system(s).
  - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status.

_Leaving this stage:_

- If any mandatory tasks failed, the run skips to completion (**Plan Errored** state).
- If any advisory tasks failed, the run proceeds to the **Planning** state, with a visible warning regarding the failed task.
- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, the run fails if there are two advisory tasks that succeed and one mandatory task that fails.
- If a user canceled the run, the run ends in the **Canceled** state.

## The Plan Stage

A run goes through different steps during the plan stage depending on whether or not HCP Terraform needs to fetch the configuration from VCS. HCP Terraform automatically archives configuration versions created through VCS when all runs are complete and then re-fetches the files for subsequent runs.

_States in this stage:_

- **Planning:** HCP Terraform is currently running `terraform plan`.
- **Needs Confirmation:** `terraform plan` has finished. Runs sometimes pause in this state, depending on the workspace and organization settings.

_Leaving this stage:_

- If the `terraform plan` command failed, the run does not continue (**Plan Errored** state).
- If a user canceled the plan by pressing the "Cancel Run" button, the run does not continue (**Canceled** state).
- If the plan succeeded with no changes and neither cost estimation nor Sentinel policy checks will be done, HCP Terraform considers the run complete (**Planned and Finished** state).
- If the plan succeeded and requires changes:
  - If cost estimation is enabled, the run proceeds automatically to the cost estimation stage.
  - If cost estimation is disabled and [Sentinel policies](/terraform/enterprise/policy-enforcement/sentinel) are enabled, the run proceeds automatically to the policy check stage.
  - If there are no Sentinel policies and the plan can be auto-applied, the run proceeds automatically to the apply stage. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))
  - If there are no Sentinel policies and HCP Terraform cannot auto-apply the plan, the run pauses in the **Needs Confirmation** state until a user with permission to apply runs takes action. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions)) If an authorized user approves the apply, the run proceeds to the apply stage. If an authorized user rejects the apply, the run does not continue (**Discarded** state).

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Note, if you want to directly integrate third-party tools and services between your plan and apply stages, see [Run Tasks](/terraform/cloud-docs/workspaces/settings/run-tasks).

## The Post-Plan Stage

The post-plan phase only occurs if you configure [run tasks](/terraform/cloud-docs/workspaces/settings/run-tasks) on a workspace to begin after Terraform successfully completes a plan operation.
All runs can enter this phase, including [speculative plans](/terraform/cloud-docs/run/remote-operations#speculative-plans). During this phase, HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue.

-> **Note:** The information sent to the configured external system includes the [JSON output](/terraform/internals/json-format) of the Terraform plan.

_States in this stage:_

- **Post-plan running:** HCP Terraform is waiting for a response from the configured external system(s).
  - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`, or the timeout will expire and the task will be assumed to be in the `failed` status.

_Leaving this stage:_

- If any mandatory tasks failed, the run skips to completion (**Plan Errored** state).
- If any advisory tasks failed, the run proceeds to the **Applying** state, with a visible warning regarding the failed task.
- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, if there are two advisory tasks that succeed and one mandatory task that failed, the run fails. If one mandatory task succeeds and two advisory tasks fail, the run succeeds with a warning.
- If a user canceled the run, the run ends in the **Canceled** state.

## The OPA Policy Check Stage

This stage only occurs if you enabled [Open Policy Agent (OPA) policies](/terraform/cloud-docs/policy-enforcement/opa) and runs after a successful `terraform plan` and before Cost Estimation. In this stage, HCP Terraform checks whether the plan adheres to the policies in the OPA policy sets for the workspace.

_States in this stage:_

- **Policy Check:** HCP Terraform is checking the plan against the OPA policy sets.
- **Policy Override:** The policy check finished, but a mandatory policy failed. The run pauses, and Terraform cannot perform an apply unless a user manually overrides the policy check failure. Refer to [Policy Results](/terraform/cloud-docs/policy-enforcement/policy-results) for details.
- **Policy Checked:** The policy check succeeded, and Terraform can apply the plan. The run may pause in this state if the workspace is not set up to auto-apply runs.

_Leaving this stage:_

If any mandatory policies failed, the run pauses in the **Policy Override** state. The run completes one of the following workflows:

- The run stops and enters the **Discarded** state when a user with [permission to apply runs](/terraform/cloud-docs/users-teams-organizations/permissions#general-workspace-permissions#manage-policy-overrides) discards the run.
- The run proceeds to the **Policy Checked** state when a user with [permission to manage policy overrides](/terraform/cloud-docs/users-teams-organizations/permissions) overrides the failed policy. The **Policy Checked** state means that no mandatory policies failed or that a user performed a manual override.

Once the run reaches the **Policy Checked** state, the run completes one of the following workflows:

- The run proceeds to the **Apply** stage if Terraform can automatically apply the plan. An auto-apply requires that the **Auto apply** setting is enabled on the workspace.
- If Terraform cannot automatically apply the plan, the run pauses in the **Policy Checked** state until a user with permission to apply runs takes action. If the user approves the apply, the run proceeds to the **Apply** stage. If the user rejects the apply, the run stops and enters the **Discarded** state.

## The Cost Estimation Stage

This stage only occurs if cost estimation is enabled. After a successful `terraform plan`, HCP Terraform uses plan data to estimate costs for each resource found in the plan.

_States in this stage:_

- **Cost Estimating:** HCP Terraform is currently estimating the resources in the plan.
- **Cost Estimated:** The cost estimate completed.

_Leaving this stage:_

- If cost estimation succeeded or errors, the run moves to the next stage.
- If there are no policy checks or applies, the run does not continue (**Planned and Finished** state).

## The Sentinel Policy Check Stage

This stage only occurs if [Sentinel policies](/terraform/cloud-docs/policy-enforcement/sentinel) are enabled. After a successful `terraform plan`, HCP Terraform checks whether the plan obeys policy to determine whether it can be applied.

_States in this stage:_

- **Policy Check:** HCP Terraform is currently checking the plan against the organization's policies.
- **Policy Override:** The policy check finished, but a soft-mandatory policy failed, so an apply cannot proceed without approval from a user with permission to manage policy overrides for the organization. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions)) The run pauses in this state.
- **Policy Checked:** The policy check succeeded, and Sentinel will allow an apply to proceed. The run sometimes pauses in this state, depending on workspace settings.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

_Leaving this stage:_

- If any hard-mandatory policies failed, the run does not continue (**Plan Errored** state).
- If any soft-mandatory policies failed, the run pauses in the **Policy Override** state.
  - If a user with permission to manage policy overrides, overrides the failed policy, the run proceeds to the **Policy Checked** state. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))
  - If a user with permission to apply runs discards the run, the run does not continue (**Discarded** state). ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))
- If the run reaches the **Policy Checked** state (no mandatory policies failed, or soft-mandatory policies were overridden):
  - If the plan can be auto-applied, the run proceeds automatically to the apply stage. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))
  - If the plan can't be auto-applied, the run pauses in the **Policy Checked** state until a user with permission to apply runs takes action. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions)) The run proceeds to the apply stage if they approve the apply, or does not continue (**Discarded** state) if they reject the apply.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

## The Pre-Apply Stage

The pre-apply phase only occurs if the workspace has [run tasks](/terraform/cloud-docs/workspaces/settings/run-tasks) configured to begin before Terraform creates the apply. HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue. The information sent to the external system includes the configuration version of the run.

Only confirmed runs can enter this phase.

_States in this stage:_

- **Pre-apply running:** HCP Terraform is waiting for a response from the configured external system(s).
  - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status.

_Leaving this stage:_

- If any mandatory tasks failed, the run skips to completion.
- If any advisory tasks failed, the run proceeds to the **Applying** state, with a visible warning regarding the failed task.
- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, the run fails if there are two advisory tasks that succeed and one mandatory task that fails.
- If a user canceled the run, the run ends in the **Canceled** state.

## The Apply Stage

_States in this stage:_

- **Applying:** HCP Terraform is currently running `terraform apply`.

_Leaving this stage:_

After applying, the run proceeds automatically to completion.

- If the apply succeeded, the run ends in the **Applied** state.
- If the apply failed, the run ends in the **Apply Errored** state.
- If a user canceled the apply by pressing **Cancel Run**, the run ends in the **Canceled** state.

## The Post-Apply Stage

The post-apply phase only occurs if you configure [run tasks](/terraform/cloud-docs/workspaces/settings/run-tasks) on a workspace to begin after Terraform successfully completes an apply operation. During this phase, HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response. However, unlike other stages in the run task process, a failed outcome does not halt the run since HCP Terraform has already provisioned the infrastructure.

_States in this stage:_

- **Post-apply running:** HCP Terraform is waiting for a response from the configured external system(s).
- External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status.

_Leaving this stage:_

- There are only advisory tasks on this stage.
- If any advisory tasks failed, the run proceeds to the **Applied** state, with a visible warning regarding the failed task.
- If a user cancels the run, the run ends in the **Canceled** state.

## Completion

A run is complete if it finishes applying, if any part of the run fails, if there is nothing to do, or if a user chooses not to continue. Once a run completes, the next run in the queue can enter the plan stage.

_States in this stage:_

- **Applied:** The run was successfully applied.
- **Planned and Finished:** `terraform plan`'s output already matches the current infrastructure state, so `terraform apply` doesn't need to do anything.
- **Apply Errored:** The `terraform apply` command failed, possibly due to a missing or misconfigured provider or an illegal operation on a provider.
- **Plan Errored:** The `terraform plan` command failed (usually requiring fixes to variables or code), or a hard-mandatory Sentinel policy failed. The run cannot be applied.
- **Discarded:** A user chose not to continue this run.
- **Canceled:** A user interrupted the `terraform plan` or `terraform apply` command with the "Cancel Run" button.

page title  Run States and Stages   Runs   HCP Terraform description       Learn what happens during each stage of a run  pending  plan  cost estimation    policy check  apply  and complete         Run States and Stages  Each plan and apply run passes through several stages of action  pending  plan  cost estimation  policy check  apply  and completion  HCP Terraform shows a run s progress through each stage as a run state   In the list of workspaces on HCP Terraform s main page  each workspace shows the state of the run it s currently processing  If no run is in progress  HCP Terraform displays the state of the most recently completed run      The Pending Stage   States in this stage        Pending    HCP Terraform hasn t started action on a run yet  HCP Terraform processes each workspace s runs in the order they were queued  and a run remains pending until every run before it has completed    Leaving this stage      If the user discards the run before it starts  the run does not continue    Discarded   state     If the run is first in the queue  it proceeds automatically to the plan stage    Planning   state       The Fetching Stage  HCP Terraform may need to fetch the configuration from VCS prior to starting the plan  HCP Terraform automatically archives configuration versions created through VCS when all runs are complete and then re fetches the files for subsequent runs    States in this stage        Fetching    If HCP Terraform has not yet fetched the configuration from VCS  the run will go into this state until the configuration is available    Leaving this stage      If HCP Terraform encounters an error when fetching the configuration from VCS  the run does not continue    Plan Errored   state     If Terraform successfully fetches the configuration  the run moves to the next stage      The Pre Plan Stage  The pre plan phase only occurs if there are enabled  run tasks   terraform cloud docs workspaces settings run tasks  in the workspace that are configured to begin before Terraform creates the plan  HCP Terraform sends information about the run to the configured external system and waits for a  passed  or  failed  response to determine whether the run can continue  The information sent to the external system includes the configuration version of the run   All runs can enter this phase  including  speculative plans   terraform cloud docs run remote operations speculative plans     States in this stage        Pre plan running    HCP Terraform is waiting for a response from the configured external system s       External systems must respond initially with a  200 OK  acknowledging the request is in progress  After that  they have 10 minutes to return a status of  passed    running   or  failed   If the timeout expires  HCP Terraform assumes that the run tasks is in the  failed  status    Leaving this stage      If any mandatory tasks failed  the run skips to completion    Plan Errored   state     If any advisory tasks failed  the run proceeds to the   Planning   state  with a visible warning regarding the failed task    If a single run has a combination of mandatory and advisory tasks  Terraform takes the most restrictive action  For example  the run fails if there are two advisory tasks that succeed and one mandatory task that fails    If a user canceled the run  the run ends in the   Canceled   state      The Plan Stage  A run goes through different steps during the plan stage depending on whether or not HCP Terraform needs to fetch the configuration from VCS  HCP Terraform automatically archives configuration versions created through VCS when all runs are complete and then re fetches the files for subsequent runs    States in this stage        Planning    HCP Terraform is currently running  terraform plan       Needs Confirmation     terraform plan  has finished  Runs sometimes pause in this state  depending on the workspace and organization settings    Leaving this stage      If the  terraform plan  command failed  the run does not continue    Plan Errored   state     If a user canceled the plan by pressing the  Cancel Run  button  the run does not continue    Canceled   state     If the plan succeeded with no changes and neither cost estimation nor Sentinel policy checks will be done  HCP Terraform considers the run complete    Planned and Finished   state     If the plan succeeded and requires changes      If cost estimation is enabled  the run proceeds automatically to the cost estimation stage      If cost estimation is disabled and  Sentinel policies   terraform enterprise policy enforcement sentinel  are enabled  the run proceeds automatically to the policy check stage      If there are no Sentinel policies and the plan can be auto applied  the run proceeds automatically to the apply stage  Plans can be auto applied if the auto apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs    More about permissions    terraform cloud docs users teams organizations permissions       If there are no Sentinel policies and HCP Terraform cannot auto apply the plan  the run pauses in the   Needs Confirmation   state until a user with permission to apply runs takes action    More about permissions    terraform cloud docs users teams organizations permissions   If an authorized user approves the apply  the run proceeds to the apply stage  If an authorized user rejects the apply  the run does not continue    Discarded   state     permissions citation    intentionally unused   keep for maintainers  Note  if you want to directly integrate third party tools and services between your plan and apply stages  see  Run Tasks   terraform cloud docs workspaces settings run tasks       The Post Plan Stage  The post plan phase only occurs if you configure  run tasks   terraform cloud docs workspaces settings run tasks  on a workspace to begin after Terraform successfully completes a plan operation  All runs can enter this phase  including  speculative plans   terraform cloud docs run remote operations speculative plans   During this phase  HCP Terraform sends information about the run to the configured external system and waits for a  passed  or  failed  response to determine whether the run can continue        Note    The information sent to the configured external system includes the  JSON output   terraform internals json format  of the Terraform plan    States in this stage        Post plan running    HCP Terraform is waiting for a response from the configured external system s       External systems must respond initially with a  200 OK  acknowledging the request is in progress  After that  they have 10 minutes to return a status of  passed    running   or  failed   or the timeout will expire and the task will be assumed to be in the  failed  status    Leaving this stage      If any mandatory tasks failed  the run skips to completion    Plan Errored   state     If any advisory tasks failed  the run proceeds to the   Applying   state  with a visible warning regarding the failed task    If a single run has a combination of mandatory and advisory tasks  Terraform takes the most restrictive action  For example  if there are two advisory tasks that succeed and one mandatory task that failed  the run fails  If one mandatory task succeeds and two advisory tasks fail  the run succeeds with a warning    If a user canceled the run  the run ends in the   Canceled   state      The OPA Policy Check Stage  This stage only occurs if you enabled  Open Policy Agent  OPA  policies   terraform cloud docs policy enforcement opa  and runs after a successful  terraform plan  and before Cost Estimation  In this stage  HCP Terraform checks whether the plan adheres to the policies in the OPA policy sets for the workspace    States in this stage        Policy Check    HCP Terraform is checking the plan against the OPA policy sets      Policy Override    The policy check finished  but a mandatory policy failed  The run pauses  and Terraform cannot perform an apply unless a user manually overrides the policy check failure  Refer to  Policy Results   terraform cloud docs policy enforcement policy results  for details      Policy Checked    The policy check succeeded  and Terraform can apply the plan  The run may pause in this state if the workspace is not set up to auto apply runs    Leaving this stage    If any mandatory policies failed  the run pauses in the   Policy Override   state  The run completes one of the following workflows     The run stops and enters the   Discarded   state when a user with  permission to apply runs   terraform cloud docs users teams organizations permissions general workspace permissions manage policy overrides  discards the run    The run proceeds to the   Policy Checked   state when a user with  permission to manage policy overrides   terraform cloud docs users teams organizations permissions  overrides the failed policy  The   Policy Checked   state means that no mandatory policies failed or that a user performed a manual override   Once the run reaches the   Policy Checked   state  the run completes one of the following workflows     The run proceeds to the   Apply   stage if Terraform can automatically apply the plan  An auto apply requires that the   Auto apply   setting is enabled on the workspace    If Terraform cannot automatically apply the plan  the run pauses in the   Policy Checked   state until a user with permission to apply runs takes action  If the user approves the apply  the run proceeds to the   Apply   stage  If the user rejects the apply  the run stops and enters the   Discarded   state      The Cost Estimation Stage  This stage only occurs if cost estimation is enabled  After a successful  terraform plan   HCP Terraform uses plan data to estimate costs for each resource found in the plan    States in this stage        Cost Estimating    HCP Terraform is currently estimating the resources in the plan      Cost Estimated    The cost estimate completed    Leaving this stage      If cost estimation succeeded or errors  the run moves to the next stage    If there are no policy checks or applies  the run does not continue    Planned and Finished   state       The Sentinel Policy Check Stage  This stage only occurs if  Sentinel policies   terraform cloud docs policy enforcement sentinel  are enabled  After a successful  terraform plan   HCP Terraform checks whether the plan obeys policy to determine whether it can be applied    States in this stage        Policy Check    HCP Terraform is currently checking the plan against the organization s policies      Policy Override    The policy check finished  but a soft mandatory policy failed  so an apply cannot proceed without approval from a user with permission to manage policy overrides for the organization    More about permissions    terraform cloud docs users teams organizations permissions   The run pauses in this state      Policy Checked    The policy check succeeded  and Sentinel will allow an apply to proceed  The run sometimes pauses in this state  depending on workspace settings    permissions citation    intentionally unused   keep for maintainers   Leaving this stage      If any hard mandatory policies failed  the run does not continue    Plan Errored   state     If any soft mandatory policies failed  the run pauses in the   Policy Override   state      If a user with permission to manage policy overrides  overrides the failed policy  the run proceeds to the   Policy Checked   state    More about permissions    terraform cloud docs users teams organizations permissions       If a user with permission to apply runs discards the run  the run does not continue    Discarded   state     More about permissions    terraform cloud docs users teams organizations permissions     If the run reaches the   Policy Checked   state  no mandatory policies failed  or soft mandatory policies were overridden       If the plan can be auto applied  the run proceeds automatically to the apply stage  Plans can be auto applied if the auto apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs    More about permissions    terraform cloud docs users teams organizations permissions       If the plan can t be auto applied  the run pauses in the   Policy Checked   state until a user with permission to apply runs takes action    More about permissions    terraform cloud docs users teams organizations permissions   The run proceeds to the apply stage if they approve the apply  or does not continue    Discarded   state  if they reject the apply    permissions citation    intentionally unused   keep for maintainers     The Pre Apply Stage  The pre apply phase only occurs if the workspace has  run tasks   terraform cloud docs workspaces settings run tasks  configured to begin before Terraform creates the apply  HCP Terraform sends information about the run to the configured external system and waits for a  passed  or  failed  response to determine whether the run can continue  The information sent to the external system includes the configuration version of the run   Only confirmed runs can enter this phase    States in this stage        Pre apply running    HCP Terraform is waiting for a response from the configured external system s       External systems must respond initially with a  200 OK  acknowledging the request is in progress  After that  they have 10 minutes to return a status of  passed    running   or  failed   If the timeout expires  HCP Terraform assumes that the run tasks is in the  failed  status    Leaving this stage      If any mandatory tasks failed  the run skips to completion    If any advisory tasks failed  the run proceeds to the   Applying   state  with a visible warning regarding the failed task    If a single run has a combination of mandatory and advisory tasks  Terraform takes the most restrictive action  For example  the run fails if there are two advisory tasks that succeed and one mandatory task that fails    If a user canceled the run  the run ends in the   Canceled   state      The Apply Stage   States in this stage        Applying    HCP Terraform is currently running  terraform apply     Leaving this stage    After applying  the run proceeds automatically to completion     If the apply succeeded  the run ends in the   Applied   state    If the apply failed  the run ends in the   Apply Errored   state    If a user canceled the apply by pressing   Cancel Run    the run ends in the   Canceled   state      The Post Apply Stage  The post apply phase only occurs if you configure  run tasks   terraform cloud docs workspaces settings run tasks  on a workspace to begin after Terraform successfully completes an apply operation  During this phase  HCP Terraform sends information about the run to the configured external system and waits for a  passed  or  failed  response  However  unlike other stages in the run task process  a failed outcome does not halt the run since HCP Terraform has already provisioned the infrastructure    States in this stage        Post apply running    HCP Terraform is waiting for a response from the configured external system s     External systems must respond initially with a  200 OK  acknowledging the request is in progress  After that  they have 10 minutes to return a status of  passed    running   or  failed   If the timeout expires  HCP Terraform assumes that the run tasks is in the  failed  status    Leaving this stage      There are only advisory tasks on this stage    If any advisory tasks failed  the run proceeds to the   Applied   state  with a visible warning regarding the failed task    If a user cancels the run  the run ends in the   Canceled   state      Completion  A run is complete if it finishes applying  if any part of the run fails  if there is nothing to do  or if a user chooses not to continue  Once a run completes  the next run in the queue can enter the plan stage    States in this stage        Applied    The run was successfully applied      Planned and Finished     terraform plan  s output already matches the current infrastructure state  so  terraform apply  doesn t need to do anything      Apply Errored    The  terraform apply  command failed  possibly due to a missing or misconfigured provider or an illegal operation on a provider      Plan Errored    The  terraform plan  command failed  usually requiring fixes to variables or code   or a hard mandatory Sentinel policy failed  The run cannot be applied      Discarded    A user chose not to continue this run      Canceled    A user interrupted the  terraform plan  or  terraform apply  command with the  Cancel Run  button


terraform Run Terraform remotely through the UI API or CLI Learn how HCP Terraform page title Remote Operations HCP Terraform Hands on Try the Get Started HCP Terraform terraform tutorials cloud get started utm source WEBSITE utm medium WEB IO utm offer ARTICLE PAGE utm content DOCS tutorials Remote Operations manages runs

Answer:
---
page_title: Remote Operations - HCP Terraform
description: >-
  Run Terraform remotely through the UI, API, or CLI. Learn how HCP Terraform
  manages runs.
---

# Remote Operations

> **Hands-on:** Try the [Get Started — HCP Terraform](/terraform/tutorials/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials.

HCP Terraform provides a central interface for running Terraform within a large collaborative organization. If you're accustomed to running Terraform from your workstation, the way HCP Terraform manages runs can be unfamiliar.

This page describes the basics of how runs work in HCP Terraform.

## Remote Operations

HCP Terraform is designed as an execution platform for Terraform, and can perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment, and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more.

Terraform runs managed by HCP Terraform are called _remote operations._ Remote runs can be initiated by webhooks from your VCS provider, by UI controls within HCP Terraform, by API calls, or by Terraform CLI. When using Terraform CLI to perform remote operations, the progress of the run is streamed to the user's terminal, to provide an experience equivalent to local operations.

### Disabling Remote Operations

[execution_mode]: /terraform/cloud-docs/workspaces/settings#execution-mode

Many of HCP Terraform's features rely on remote execution and are not available when using local operations. This includes features like Sentinel policy enforcement, cost estimation, and notifications.

You can disable remote operations for any workspace by changing its [Execution Mode][execution_mode] to **Local**. This causes the workspace to act only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers.

### Protecting Private Environments

[HCP Terraform agents](/terraform/cloud-docs/agents) are a paid feature that allows HCP Terraform to communicate with isolated, private, or on-premises infrastructure. The agent polls HCP Terraform or Terraform Enterprise for any changes to your configuration and executes the changes locally, so you do not need to allow public ingress traffic to your resources. Agents allow you to control infrastructure in private environments without modifying your network perimeter.

HCP Terraform agents also support running custom programs, called _hooks_, during strategic points of a Terraform run. For example, you may create a hook to dynamically download software required by the Terraform run or send an HTTP request to a system to kick off an external workflow.

## Runs and Workspaces

HCP Terraform always performs Terraform runs in the context of a [workspace](/terraform/cloud-docs/run/remote-operations). The workspace serves the same role that a persistent working directory serves when running Terraform locally: it provides the configuration, state, and variables for the run.

### Configuration Versions

Each workspace is associated with a particular Terraform configuration, but that configuration is expected to change over time. Thus, HCP Terraform manages configurations as a series of _configuration versions._

Most commonly, a workspace is linked to a VCS repository, and its configuration versions are tied to revisions in the specified VCS branch. In workspaces that aren't linked to a repository, new configuration versions can be uploaded via Terraform CLI or via the API.

### Ordering and Timing

Each workspace in HCP Terraform maintains its own queue of runs, and processes those runs in order.

Whenever a new run is initiated, it's added to the end of the queue. If there's already a run in progress, the new run won't start until the current one has completely finished — HCP Terraform won't even plan the run yet, because the current run might change what a future run would do. Runs that are waiting for other runs to finish are in a _pending_ state, and a workspace might have any number of pending runs.

There are two exceptions to the run queue, which can proceed at any time and do not block the progress of other runs:

- Plan-only runs.
- The planning stages of [saved plan runs](/terraform/cloud-docs/run/modes-and-options/#saved-plans). You can only _apply_ a saved plan if no other run is in progress, and applying that plan blocks the run queue as usual. Terraform Enterprise does not yet support this workflow.

When you initiate a run, HCP Terraform locks the run to a particular configuration version and set of variable values. If you change variables or commit new code before the run finishes, it will only affect future runs, not runs that are already pending, planning, or awaiting apply.

### Workspace Locks

When a workspace is _locked,_ HCP Terraform can create new runs (automatically or manually), but those runs do not begin until you unlock the workspace.

When a run is in progress, that run locks the workspace, as described above under "Ordering and Timing".

There are two kinds of run operation that can ignore workspace locking:

- Plan-only runs.
- The planning stages of [saved plan runs](/terraform/cloud-docs/run/modes-and-options/#saved-plans). You can only _apply_ a saved plan if the workspace is unlocked, and applying that plan locks the workspace as usual. Terraform Enterprise does not yet support this workflow.

A user or team can also deliberately lock a workspace, to perform maintenance or for any other reason. For more details, see [Locking Workspaces (Preventing Runs)](/terraform/cloud-docs/run/manage#locking-workspaces-preventing-runs-).

## Starting Runs

HCP Terraform has three main workflows for managing runs, and your chosen workflow determines when and how Terraform runs occur. For detailed information, see:

- The [UI/VCS-driven run workflow](/terraform/cloud-docs/run/ui), which is the primary mode of operation.
- The [API-driven run workflow](/terraform/cloud-docs/run/api), which is more flexible but requires you to create some tooling.
- The [CLI-driven run workflow](/terraform/cloud-docs/run/cli), which uses Terraform's standard CLI tools to execute runs in HCP Terraform.

You can use the following methods to initiate HCP Terraform runs:
- Click the **+ New run** button on the workspace's page
- Implement VCS webhooks
- Run the standard `terraform apply` command when the CLI integration is configured
- Call [the Runs API](/terraform/cloud-docs/api-docs/run) using any API tool

## Plans and Applies

HCP Terraform enforces Terraform's division between _plan_ and _apply_ operations. It always plans first, then uses that plan's output for the apply.

In the default configuration, HCP Terraform waits for user approval before running an apply, but you can configure workspaces to [automatically apply](/terraform/cloud-docs/workspaces/settings#auto-apply-and-manual-apply) successful plans. Some plans can't be auto-applied, like plans queued by [run triggers](/terraform/cloud-docs/workspaces/settings/run-triggers) or by users without permission to apply runs for the workspace. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

If a plan contains no changes, HCP Terraform does not attempt to apply it. Instead, the run ends with a status of "Planned and finished". The [allow empty apply](/terraform/cloud-docs/run/modes-and-options#allow-empty-apply) run mode can override this behavior.

### Speculative Plans

In addition to normal runs, HCP Terraform can run _speculative plans_ to test changes to a configuration during editing and code review. Speculative plans are plan-only runs. They show possible changes, and policies affected by those changes, but cannot apply any changes.

Speculative plans can begin without waiting for other runs to finish because they don't affect real infrastructure. HCP Terraform lists past speculative plan runs alongside a workspace's other runs.

There are three ways to run speculative plans:

- In VCS-backed workspaces, pull requests start speculative plans, and the VCS provider's pull request interface includes a link to the plan. See [UI/VCS Runs: Speculative Plans on Pull Requests](/terraform/cloud-docs/run/ui#speculative-plans-on-pull-requests) for more details.
- With the [CLI integration](/terraform/cli/cloud) configured, running `terraform plan` on the command line starts a speculative plan. The plan output streams to the terminal, and a link to the plan is also included.
- The runs API creates speculative plans whenever the specified configuration version is marked as speculative. See [the `configuration-versions` API](/terraform/cloud-docs/api-docs/configuration-versions#create-a-configuration-version) for more information.

#### Retry a speculative plan in the UI

If a speculative plan fails due to an external factor, you can run it again using the "Retry Run" button on its page:

Retrying a plan requires permission to queue plans for that workspace. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions)) Only failed or canceled plans can be retried.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Retrying the run will create a new run with the same configuration version. If it is a VCS-backed workspace, the pull request interface will receive the status of the new run, along with a link to the new run.

### Saved Plans

-> **Version note:** Using saved plans from the CLI with HCP Terraform requires at least Terraform CLI v1.6.0.

HCP Terraform also supports saved plan runs. If you have configured the [CLI integration](/terraform/cli/cloud) you can use `terraform plan -out <FILE>` to perform and save a plan, `terraform apply <FILE>` to apply a saved plan, and `terraform show <FILE>` to inspect a saved plan before applying it. You can also create saved plan runs via the API by using the `save-plan` option.

Saved plan runs affect the run queue differently from normal runs, and can sometimes be automatically discarded. For more details, refer to [Run Modes and Options: Saved Plans](/terraform/cloud-docs/run/modes-and-options#saved-plans).

## Planning Modes and Options

In addition to the normal run workflows described above, HCP Terraform supports destroy runs, refresh-only runs, and several planning options that can modify the behavior of a run. For more details, see [Run Modes and Options](/terraform/cloud-docs/run/modes-and-options).

## Run States

HCP Terraform shows the progress of each run as it passes through each run state (pending, plan, policy check, apply, and completion). In some states, the run might require confirmation before continuing or ending; see [Managing Runs: Interacting with Runs](/terraform/cloud-docs/run/manage#interacting-with-runs) for more information.

In the list of workspaces on HCP Terraform's main page, each workspace shows the state of the run it's currently processing. (Or, if no run is in progress, the state of the most recent completed run.)

For full details about the stages of a run, see [Run States and Stages][].

[Run States and Stages]: /terraform/cloud-docs/run/states

## Import

We recommend using [`import` blocks](/terraform/language/import), introduced in Terraform 1.5, to import resources in HCP Terraform.

HCP Terraform does not support remote execution for the `terraform import` command. For this command the workspace acts only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers.

Since `terraform import` runs locally, environment variables defined in the workspace are not available. Any environment variables required by the provider you're importing from must be defined within your local execution scope.

page title  Remote Operations   HCP Terraform description       Run Terraform remotely through the UI  API  or CLI  Learn how HCP Terraform   manages runs         Remote Operations      Hands on    Try the  Get Started   HCP Terraform   terraform tutorials cloud get started utm source WEBSITE utm medium WEB IO utm offer ARTICLE PAGE utm content DOCS  tutorials   HCP Terraform provides a central interface for running Terraform within a large collaborative organization  If you re accustomed to running Terraform from your workstation  the way HCP Terraform manages runs can be unfamiliar   This page describes the basics of how runs work in HCP Terraform      Remote Operations  HCP Terraform is designed as an execution platform for Terraform  and can perform Terraform runs on its own disposable virtual machines  This provides a consistent and reliable run environment  and enables advanced features like Sentinel policy enforcement  cost estimation  notifications  version control integration  and more   Terraform runs managed by HCP Terraform are called  remote operations   Remote runs can be initiated by webhooks from your VCS provider  by UI controls within HCP Terraform  by API calls  or by Terraform CLI  When using Terraform CLI to perform remote operations  the progress of the run is streamed to the user s terminal  to provide an experience equivalent to local operations       Disabling Remote Operations   execution mode    terraform cloud docs workspaces settings execution mode  Many of HCP Terraform s features rely on remote execution and are not available when using local operations  This includes features like Sentinel policy enforcement  cost estimation  and notifications   You can disable remote operations for any workspace by changing its  Execution Mode  execution mode  to   Local    This causes the workspace to act only as a remote backend for Terraform state  with all execution occurring on your own workstations or continuous integration workers       Protecting Private Environments   HCP Terraform agents   terraform cloud docs agents  are a paid feature that allows HCP Terraform to communicate with isolated  private  or on premises infrastructure  The agent polls HCP Terraform or Terraform Enterprise for any changes to your configuration and executes the changes locally  so you do not need to allow public ingress traffic to your resources  Agents allow you to control infrastructure in private environments without modifying your network perimeter   HCP Terraform agents also support running custom programs  called  hooks   during strategic points of a Terraform run  For example  you may create a hook to dynamically download software required by the Terraform run or send an HTTP request to a system to kick off an external workflow      Runs and Workspaces  HCP Terraform always performs Terraform runs in the context of a  workspace   terraform cloud docs run remote operations   The workspace serves the same role that a persistent working directory serves when running Terraform locally  it provides the configuration  state  and variables for the run       Configuration Versions  Each workspace is associated with a particular Terraform configuration  but that configuration is expected to change over time  Thus  HCP Terraform manages configurations as a series of  configuration versions    Most commonly  a workspace is linked to a VCS repository  and its configuration versions are tied to revisions in the specified VCS branch  In workspaces that aren t linked to a repository  new configuration versions can be uploaded via Terraform CLI or via the API       Ordering and Timing  Each workspace in HCP Terraform maintains its own queue of runs  and processes those runs in order   Whenever a new run is initiated  it s added to the end of the queue  If there s already a run in progress  the new run won t start until the current one has completely finished   HCP Terraform won t even plan the run yet  because the current run might change what a future run would do  Runs that are waiting for other runs to finish are in a  pending  state  and a workspace might have any number of pending runs   There are two exceptions to the run queue  which can proceed at any time and do not block the progress of other runs     Plan only runs    The planning stages of  saved plan runs   terraform cloud docs run modes and options  saved plans   You can only  apply  a saved plan if no other run is in progress  and applying that plan blocks the run queue as usual  Terraform Enterprise does not yet support this workflow   When you initiate a run  HCP Terraform locks the run to a particular configuration version and set of variable values  If you change variables or commit new code before the run finishes  it will only affect future runs  not runs that are already pending  planning  or awaiting apply       Workspace Locks  When a workspace is  locked   HCP Terraform can create new runs  automatically or manually   but those runs do not begin until you unlock the workspace   When a run is in progress  that run locks the workspace  as described above under  Ordering and Timing    There are two kinds of run operation that can ignore workspace locking     Plan only runs    The planning stages of  saved plan runs   terraform cloud docs run modes and options  saved plans   You can only  apply  a saved plan if the workspace is unlocked  and applying that plan locks the workspace as usual  Terraform Enterprise does not yet support this workflow   A user or team can also deliberately lock a workspace  to perform maintenance or for any other reason  For more details  see  Locking Workspaces  Preventing Runs    terraform cloud docs run manage locking workspaces preventing runs        Starting Runs  HCP Terraform has three main workflows for managing runs  and your chosen workflow determines when and how Terraform runs occur  For detailed information  see     The  UI VCS driven run workflow   terraform cloud docs run ui   which is the primary mode of operation    The  API driven run workflow   terraform cloud docs run api   which is more flexible but requires you to create some tooling    The  CLI driven run workflow   terraform cloud docs run cli   which uses Terraform s standard CLI tools to execute runs in HCP Terraform   You can use the following methods to initiate HCP Terraform runs     Click the     New run   button on the workspace s page   Implement VCS webhooks    Run the standard  terraform apply  command when the CLI integration is configured   Call  the Runs API   terraform cloud docs api docs run  using any API tool     Plans and Applies  HCP Terraform enforces Terraform s division between  plan  and  apply  operations  It always plans first  then uses that plan s output for the apply   In the default configuration  HCP Terraform waits for user approval before running an apply  but you can configure workspaces to  automatically apply   terraform cloud docs workspaces settings auto apply and manual apply  successful plans  Some plans can t be auto applied  like plans queued by  run triggers   terraform cloud docs workspaces settings run triggers  or by users without permission to apply runs for the workspace    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers  If a plan contains no changes  HCP Terraform does not attempt to apply it  Instead  the run ends with a status of  Planned and finished   The  allow empty apply   terraform cloud docs run modes and options allow empty apply  run mode can override this behavior       Speculative Plans  In addition to normal runs  HCP Terraform can run  speculative plans  to test changes to a configuration during editing and code review  Speculative plans are plan only runs  They show possible changes  and policies affected by those changes  but cannot apply any changes   Speculative plans can begin without waiting for other runs to finish because they don t affect real infrastructure  HCP Terraform lists past speculative plan runs alongside a workspace s other runs   There are three ways to run speculative plans     In VCS backed workspaces  pull requests start speculative plans  and the VCS provider s pull request interface includes a link to the plan  See  UI VCS Runs  Speculative Plans on Pull Requests   terraform cloud docs run ui speculative plans on pull requests  for more details    With the  CLI integration   terraform cli cloud  configured  running  terraform plan  on the command line starts a speculative plan  The plan output streams to the terminal  and a link to the plan is also included    The runs API creates speculative plans whenever the specified configuration version is marked as speculative  See  the  configuration versions  API   terraform cloud docs api docs configuration versions create a configuration version  for more information        Retry a speculative plan in the UI  If a speculative plan fails due to an external factor  you can run it again using the  Retry Run  button on its page   Retrying a plan requires permission to queue plans for that workspace    More about permissions    terraform cloud docs users teams organizations permissions   Only failed or canceled plans can be retried    permissions citation    intentionally unused   keep for maintainers  Retrying the run will create a new run with the same configuration version  If it is a VCS backed workspace  the pull request interface will receive the status of the new run  along with a link to the new run       Saved Plans       Version note    Using saved plans from the CLI with HCP Terraform requires at least Terraform CLI v1 6 0   HCP Terraform also supports saved plan runs  If you have configured the  CLI integration   terraform cli cloud  you can use  terraform plan  out  FILE   to perform and save a plan   terraform apply  FILE   to apply a saved plan  and  terraform show  FILE   to inspect a saved plan before applying it  You can also create saved plan runs via the API by using the  save plan  option   Saved plan runs affect the run queue differently from normal runs  and can sometimes be automatically discarded  For more details  refer to  Run Modes and Options  Saved Plans   terraform cloud docs run modes and options saved plans       Planning Modes and Options  In addition to the normal run workflows described above  HCP Terraform supports destroy runs  refresh only runs  and several planning options that can modify the behavior of a run  For more details  see  Run Modes and Options   terraform cloud docs run modes and options       Run States  HCP Terraform shows the progress of each run as it passes through each run state  pending  plan  policy check  apply  and completion   In some states  the run might require confirmation before continuing or ending  see  Managing Runs  Interacting with Runs   terraform cloud docs run manage interacting with runs  for more information   In the list of workspaces on HCP Terraform s main page  each workspace shows the state of the run it s currently processing   Or  if no run is in progress  the state of the most recent completed run    For full details about the stages of a run  see  Run States and Stages       Run States and Stages    terraform cloud docs run states     Import  We recommend using   import  blocks   terraform language import   introduced in Terraform 1 5  to import resources in HCP Terraform   HCP Terraform does not support remote execution for the  terraform import  command  For this command the workspace acts only as a remote backend for Terraform state  with all execution occurring on your own workstations or continuous integration workers   Since  terraform import  runs locally  environment variables defined in the workspace are not available  Any environment variables required by the provider you re importing from must be defined within your local execution scope


terraform Terraform relies on provider plugins to manage resources In most cases Terraform can automatically download the required plugins but there are cases where plugins must be managed explicitly Installing Software in the Run Environment Learn how to install Terraform providers and additional software on Terraform Cloud workers including cloud CLIs or configuration management tools page title Installing Software in the Run Environment Runs HCP Terraform

Answer:
---
page_title: Installing Software in the Run Environment - Runs - HCP Terraform
description: >-
  Learn how to install Terraform providers and additional software on Terraform
  Cloud workers, including cloud CLIs or configuration management tools.
---

# Installing Software in the Run Environment

Terraform relies on provider plugins to manage resources. In most cases, Terraform can automatically download the required plugins, but there are cases where plugins must be managed explicitly.

In rare cases, it might also be necessary to install extra software on the Terraform worker, such as a configuration management tool or cloud CLI.

## Installing Terraform Providers

The mechanics of provider installation changed in Terraform 0.13, thanks to the introduction of the [Terraform Registry][registry] for providers which allows custom and community providers to be installed via `terraform init`. Prior to Terraform 0.13, Terraform could only automatically install providers distributed by HashiCorp.

### Terraform 0.13 and later

#### Providers From the Terraform Registry

The [Terraform Registry][registry] allows anyone to publish and distribute providers which can be automatically downloaded and installed via `terraform init`.

Terraform Enterprise instances must be able to access `registry.terraform.io` to use providers from the public registry; otherwise, you can install providers using [the `terraform-bundle` tool][bundle].

[registry]: https://registry.terraform.io/browse/providers

#### In-House Providers

If you have a custom provider that you'd rather not publish in the public Terraform Registry, you have a few options:

- Add the provider binary to the VCS repo (or manually-uploaded configuration version). Place the compiled `linux_amd64` version of the plugin at `terraform.d/plugins/<SOURCE HOST>/<SOURCE NAMESPACE>/<PLUGIN NAME>/<VERSION>/linux_amd64`, relative to the root of the directory.

  The source host and namespace will need to match the source given in the  `required_providers` block within the configuration, but can otherwise be arbitrary identifiers. For instance, if your `required_providers` block looks like this:

  ```
  terraform {
    required_providers {
      custom = {
        source = "my-host/my-namespace/custom"
        version = "1.0.0"
      }
    }
  }
  ```

  HCP Terraform will be able to use your compiled provider if you place it at `terraform.d/plugins/my-host/my-namespace/custom/1.0.0/linux_amd64/terraform-provider-custom`.

- Use a privately-owned provider registry service which implements the [provider registry protocol](/terraform/internals/provider-registry-protocol) to distribute custom providers. Be sure to include the full [source address](/terraform/language/providers/requirements#source-addresses), including the hostname, when referencing providers.

- **Terraform Enterprise only:** Use [the `terraform-bundle` tool][bundle] to add custom providers.

-> **Note:** Using a [network mirror](/terraform/internals/provider-network-mirror-protocol) to host custom providers for installation is not currently supported in HCP Terraform, since the network mirror cannot be activated without a [`provider_installation`](/terraform/cli/config/config-file#explicit-installation-method-configuration) block in the CLI configuration file.

### Terraform 0.12 and earlier

#### Providers Distributed by HashiCorp

HCP Terraform can automatically install providers distributed by HashiCorp. Terraform Enterprise instances can do this as well as long as they can access `releases.hashicorp.com`.

If that isn't feasible due to security requirements, you can manually install providers. Use [the `terraform-bundle` tool][bundle] to build a custom version of Terraform that includes the necessary providers, and configure your workspaces to use that bundled version.

[bundle]: https://github.com/hashicorp/terraform/tree/master/tools/terraform-bundle#installing-a-bundle-in-on-premises-terraform-enterprise

#### Custom and Community Providers

To use community providers or your own custom providers with Terraform versions prior to 0.13, you must install them yourself.

There are two ways to accomplish this:

- Add the provider binary to the VCS repo (or manually-uploaded configuration version) for any workspace that uses it. Place the compiled `linux_amd64` version of the plugin at `terraform.d/plugins/linux_amd64/<PLUGIN NAME>` (as a relative path from the root of the working directory). The plugin name should follow the [naming scheme](/terraform/language/v1.1.x/configuration-0-11/providers#plugin-names-and-versions) and the plugin file must have read and execute permissions. (Third-party plugins are often distributed with an appropriate filename already set in the distribution archive.)

  You can add plugins directly to a configuration repo, or you can add them as Git submodules and symlink the executable files into `terraform.d/plugins/`. Submodules are a good choice when many workspaces use the same custom provider, since they keep your repos smaller. If using submodules, enable the ["Include submodules on clone" setting](/terraform/cloud-docs/workspaces/settings/vcs#include-submodules-on-clone) on any affected workspace.

- **Terraform Enterprise only:** Use [the `terraform-bundle` tool][bundle] to add custom providers to a custom Terraform version. This keeps custom providers out of your configuration repos entirely, and is easier to update when many workspaces use the same provider.

## Installing Additional Tools

### Avoid Installing Extra Software

Whenever possible, don't install software on the worker. There are a number of reasons for this:

- Provisioners are a last resort in Terraform; they greatly increase the risk of creating unknown states with unmanaged and partially-managed infrastructure, and the `local-exec` provisioner is especially hazardous. [The Terraform CLI docs on provisioners](/terraform/language/resources/provisioners/syntax#provisioners-are-a-last-resort) explain the hazards in more detail, with more information about the preferred alternatives. (In summary: use Packer, use cloud-init, try to make your infrastructure more immutable, and always prefer real provider features.)
- We don't guarantee the stability of the operating system on the Terraform build workers. It's currently the latest version of Ubuntu LTS, but we reserve the right to change that at any time.
- The build workers are disposable and are destroyed after each use, which makes managing extra software even more complex than when running Terraform CLI in a persistent environment. Custom software must be installed on every run, which also increases run times.

### Only Install Standalone Binaries

HCP Terraform does not allow you to elevate a command's permissions with `sudo` during Terraform runs. This means you cannot install packages using the worker OS's normal package management tools. However, you can install and execute standalone binaries in Terraform's working directory.

You have two options for getting extra software into the configuration directory:

- Include it in the configuration repository as a submodule. (Make sure the workspace is configured to clone submodules.)
- Use `local-exec` to download it with `curl`. For example:

  ```hcl
  resource "aws_instance" "example" {
    ami           = "${var.ami}"
    instance_type = "t2.micro"
    provisioner "local-exec" {
      command = <<EOH
  curl -o jq https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64
  chmod 0755 jq
  # Do some kind of JSON processing with ./jq
  EOH
    }
  }
  ```

When downloading software with `local-exec`, try to associate the provisioner block with the resource(s) that the software will interact with. If you use a null resource with a `local-exec` provisioner, you must ensure it can be properly configured with [triggers](/terraform/language/resources/provisioners/null_resource#example-usage). Otherwise, a null resource with the `local-exec` provisioner will only install software on the initial run where the `null_resource` is created. The `null_resource` will not be automatically recreated in subsequent runs and the related software won't be installed, which may cause runs to encounter errors.

-> **Note:** Terraform Enterprise instances can be configured to allow `sudo` commands during Terraform runs. However, even when `sudo` is allowed, using the worker OS's package tools during runs is still usually a bad idea. You will have a much better experience if you can move your provisioner actions into a custom provider or an immutable machine image.

page title  Installing Software in the Run Environment   Runs   HCP Terraform description       Learn how to install Terraform providers and additional software on Terraform   Cloud workers  including cloud CLIs or configuration management tools         Installing Software in the Run Environment  Terraform relies on provider plugins to manage resources  In most cases  Terraform can automatically download the required plugins  but there are cases where plugins must be managed explicitly   In rare cases  it might also be necessary to install extra software on the Terraform worker  such as a configuration management tool or cloud CLI      Installing Terraform Providers  The mechanics of provider installation changed in Terraform 0 13  thanks to the introduction of the  Terraform Registry  registry  for providers which allows custom and community providers to be installed via  terraform init   Prior to Terraform 0 13  Terraform could only automatically install providers distributed by HashiCorp       Terraform 0 13 and later       Providers From the Terraform Registry  The  Terraform Registry  registry  allows anyone to publish and distribute providers which can be automatically downloaded and installed via  terraform init    Terraform Enterprise instances must be able to access  registry terraform io  to use providers from the public registry  otherwise  you can install providers using  the  terraform bundle  tool  bundle     registry   https   registry terraform io browse providers       In House Providers  If you have a custom provider that you d rather not publish in the public Terraform Registry  you have a few options     Add the provider binary to the VCS repo  or manually uploaded configuration version   Place the compiled  linux amd64  version of the plugin at  terraform d plugins  SOURCE HOST   SOURCE NAMESPACE   PLUGIN NAME   VERSION  linux amd64   relative to the root of the directory     The source host and namespace will need to match the source given in the   required providers  block within the configuration  but can otherwise be arbitrary identifiers  For instance  if your  required providers  block looks like this           terraform       required providers         custom             source    my host my namespace custom          version    1 0 0                             HCP Terraform will be able to use your compiled provider if you place it at  terraform d plugins my host my namespace custom 1 0 0 linux amd64 terraform provider custom      Use a privately owned provider registry service which implements the  provider registry protocol   terraform internals provider registry protocol  to distribute custom providers  Be sure to include the full  source address   terraform language providers requirements source addresses   including the hostname  when referencing providers       Terraform Enterprise only    Use  the  terraform bundle  tool  bundle  to add custom providers        Note    Using a  network mirror   terraform internals provider network mirror protocol  to host custom providers for installation is not currently supported in HCP Terraform  since the network mirror cannot be activated without a   provider installation    terraform cli config config file explicit installation method configuration  block in the CLI configuration file       Terraform 0 12 and earlier       Providers Distributed by HashiCorp  HCP Terraform can automatically install providers distributed by HashiCorp  Terraform Enterprise instances can do this as well as long as they can access  releases hashicorp com    If that isn t feasible due to security requirements  you can manually install providers  Use  the  terraform bundle  tool  bundle  to build a custom version of Terraform that includes the necessary providers  and configure your workspaces to use that bundled version    bundle   https   github com hashicorp terraform tree master tools terraform bundle installing a bundle in on premises terraform enterprise       Custom and Community Providers  To use community providers or your own custom providers with Terraform versions prior to 0 13  you must install them yourself   There are two ways to accomplish this     Add the provider binary to the VCS repo  or manually uploaded configuration version  for any workspace that uses it  Place the compiled  linux amd64  version of the plugin at  terraform d plugins linux amd64  PLUGIN NAME    as a relative path from the root of the working directory   The plugin name should follow the  naming scheme   terraform language v1 1 x configuration 0 11 providers plugin names and versions  and the plugin file must have read and execute permissions   Third party plugins are often distributed with an appropriate filename already set in the distribution archive      You can add plugins directly to a configuration repo  or you can add them as Git submodules and symlink the executable files into  terraform d plugins    Submodules are a good choice when many workspaces use the same custom provider  since they keep your repos smaller  If using submodules  enable the   Include submodules on clone  setting   terraform cloud docs workspaces settings vcs include submodules on clone  on any affected workspace       Terraform Enterprise only    Use  the  terraform bundle  tool  bundle  to add custom providers to a custom Terraform version  This keeps custom providers out of your configuration repos entirely  and is easier to update when many workspaces use the same provider      Installing Additional Tools      Avoid Installing Extra Software  Whenever possible  don t install software on the worker  There are a number of reasons for this     Provisioners are a last resort in Terraform  they greatly increase the risk of creating unknown states with unmanaged and partially managed infrastructure  and the  local exec  provisioner is especially hazardous   The Terraform CLI docs on provisioners   terraform language resources provisioners syntax provisioners are a last resort  explain the hazards in more detail  with more information about the preferred alternatives   In summary  use Packer  use cloud init  try to make your infrastructure more immutable  and always prefer real provider features     We don t guarantee the stability of the operating system on the Terraform build workers  It s currently the latest version of Ubuntu LTS  but we reserve the right to change that at any time    The build workers are disposable and are destroyed after each use  which makes managing extra software even more complex than when running Terraform CLI in a persistent environment  Custom software must be installed on every run  which also increases run times       Only Install Standalone Binaries  HCP Terraform does not allow you to elevate a command s permissions with  sudo  during Terraform runs  This means you cannot install packages using the worker OS s normal package management tools  However  you can install and execute standalone binaries in Terraform s working directory   You have two options for getting extra software into the configuration directory     Include it in the configuration repository as a submodule   Make sure the workspace is configured to clone submodules     Use  local exec  to download it with  curl   For example        hcl   resource  aws instance   example        ami                var ami       instance type    t2 micro      provisioner  local exec          command     EOH   curl  o jq https   github com stedolan jq releases download jq 1 6 jq linux64   chmod 0755 jq     Do some kind of JSON processing with   jq   EOH                  When downloading software with  local exec   try to associate the provisioner block with the resource s  that the software will interact with  If you use a null resource with a  local exec  provisioner  you must ensure it can be properly configured with  triggers   terraform language resources provisioners null resource example usage   Otherwise  a null resource with the  local exec  provisioner will only install software on the initial run where the  null resource  is created  The  null resource  will not be automatically recreated in subsequent runs and the related software won t be installed  which may cause runs to encounter errors        Note    Terraform Enterprise instances can be configured to allow  sudo  commands during Terraform runs  However  even when  sudo  is allowed  using the worker OS s package tools during runs is still usually a bad idea  You will have a much better experience if you can move your provisioner actions into a custom provider or an immutable machine image


terraform HCP Terraform has three workflows for managing Terraform runs The UI and VCS driven Run Workflow page title UI VCS driven Runs Runs HCP Terraform Workspaces are associated with a VCS repository branch and HCP Terraform automatically queues runs when new commits are merged

Answer:
---
page_title: UI/VCS-driven Runs - Runs - HCP Terraform
description: >-
  Workspaces are associated with a VCS repository branch, and HCP Terraform
  automatically queues runs when new commits are merged.
---

# The UI- and VCS-driven Run Workflow

HCP Terraform has three workflows for managing Terraform runs.

- The UI/VCS-driven run workflow described below, which is the primary mode of operation.
- The [API-driven run workflow](/terraform/cloud-docs/run/api), which is more flexible but requires you to create some tooling.
- The [CLI-driven run workflow](/terraform/cloud-docs/run/cli), which uses Terraform's standard CLI tools to execute runs in HCP Terraform.

## Summary

In the UI and VCS workflow, every workspace is associated with a specific branch of a VCS repo of Terraform configurations. HCP Terraform registers webhooks with your VCS provider when you create a workspace, then automatically queues a Terraform run whenever new commits are merged to that branch of workspace's linked repository.

HCP Terraform also performs a [speculative plan][] when a pull request is opened against that branch. HCP Terraform posts a link to the plan in the pull request, and re-runs the plan if the pull request is updated.

[speculative plan]: /terraform/cloud-docs/run/remote-operations#speculative-plans

The Terraform code for a normal run always comes from version control, and is always associated with a specific commit.

## Automatically Starting Runs

In a workspace linked to a VCS repository, runs start automatically when you merge or commit changes to version control.

If you use GitHub as your VCS provider and merge a PR changing 300 or more files, HCP Terraform automatically triggers runs for every workspace connected to that repository. The GitHub API has a limit of 300 reported changed files for a PR merge. To address this, HCP Terraform initiates workspace runs proactively, preventing oversight of file changes beyond this limit.

A workspace is linked to one branch of a VCS repository and ignores changes to other branches. You can specify which files and directories within your repository trigger runs. HCP Terraform can also automatically trigger runs when you create Git tags. Refer to [Automatic Run Triggering](/terraform/cloud-docs/workspaces/settings/vcs#automatic-run-triggering) for details.

-> **Note:** A workspace with no runs will not accept new runs via VCS webhook. At least one run must be manually queued to confirm that the workspace is ready for further runs.

A workspace will not process a webhook if the workspace previously processed a webhook with the same commit SHA and created a run. To trigger a run, create a new commit. If a workspace receives a webhook with a previously processed commit, HCP Terraform will add a new event to the [VCS Events](/terraform/cloud-docs/vcs#viewing-events) page documenting the received webhook.

## Manually Starting Runs

You can manually trigger a run using the UI. Manual runs let you apply configuration changes when you update variable values but the configuration in version control is unchanged. You must manually trigger an initial run in any new VCS-driven workspace.

To start a run, click the **+ New run** button on the workspace page. This opens a **Start a new run** dialog. Select the run mode and provide an optional message. Review the [run modes documentation](/terraform/cloud-docs/run/modes-and-options) for more detail on supported options.

Run modes that have a plan phase support debugging mode. This is equivalent to setting the `TF_LOG` environment variable to `TRACE` for this run only. To enable debugging, click **Additional planning options** under the run mode and click **Enable debugging mode**.  See [Debugging Terraform](/terraform/internals/debugging) for more information.

To [replace](/terraform/cloud-docs/run/modes-and-options#replacing-selected-resources) specific resources as part of a standard plan and apply run, expand the **Additional planning options** section and select the resources to replace.

Manually starting a run requires permission to queue plans for the workspace. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

If the workspace has a plan that is still in the [plan stage](/terraform/cloud-docs/run/states#the-plan-stage) when a new plan is queued, you can either wait for it to complete, or visit the **Current Run** page and click **Run this plan now**. Be aware that this action terminates the current plan and unlocks the workspace, which can lead to anomalies in behavior, but can be useful if the plans are long-running and the current plan does not have all the desired changes.

## Automatically cancel plan-only runs triggered by outdated commits

Refer to [Automatically cancel plan-only runs triggered by outdated commits](/terraform/cloud-docs/users-teams-organizations/organizations/vcs-speculative-plan-management) for additional information.

## Confirming or Discarding Plans

By default, run plans require confirmation before HCP Terraform will apply them. Users with permission to apply runs for the workspace can navigate to a run that has finished planning and click the "Confirm & Apply" or "Discard Plan" button to finish or cancel a run. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions)) If necessary, use the "View Plan" button for more details about what the run will change.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

![confirm button](/img/docs/runs-confirm.png)

Users can also leave comments if there's something unusual involved in a run.

Note that once the plan stage is completed, until you apply or discard a plan, HCP Terraform can't start another run in that workspace.

### Auto apply

If you would rather automatically apply plans that don't have errors, you can [enable auto apply](/terraform/cloud-docs/workspaces/settings#auto-apply-and-manual-apply) on the workspace's "General Settings" page. Some plans can't be auto-applied, like plans queued by [run triggers](/terraform/cloud-docs/workspaces/settings/run-triggers) or by users without permission to apply runs. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

## Speculative Plans on Pull Requests

To help you review proposed changes, HCP Terraform can automatically run [speculative plans][speculative plan] for pull requests or merge requests.

### Viewing Pull Request Plans

You can view speculative plans in a workspace's list of normal runs. Additionally, HCP Terraform adds a link to the run in the pull request itself, along with an indicator of the run's status.

A single pull request can include links to multiple plans, depending on how many workspaces connect to the destination branch. If you update a pull request, HCP Terraform performs new speculative plans and update the links.

Although any contributor to the repository can see the status indicators for pull request plans, only members of your HCP Terraform organization with permission to read runs for the affected workspaces can click through and view the complete plan output. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

### Rules for Triggering Pull Request Plans

Whenever a pull request is _created or updated,_ HCP Terraform checks whether it should run speculative plans in workspaces connected to that repository, based on the following rules:

- Only pull requests that originate from within the same repository can trigger speculative plans.

  To avoid executing malicious code or exposing sensitive information, HCP Terraform doesn't run speculative plans for pull requests that originate from forks of a repository.

  -> **Note:** On Terraform Enterprise, administrators can choose to allow speculative plans on pull requests that originate from forks. To learn more about this setting, refer to the [general settings documentation](/terraform/enterprise/admin/application/general#allow-speculative-plans-on-pull-requests-from-forks)

- Pull requests can only trigger runs in workspaces where automatic speculative plans are allowed. You can [disable automatic speculative plans](/terraform/cloud-docs/workspaces/settings/vcs#automatic-speculative-plans) in a workspace's VCS settings.

- A pull request will only trigger speculative plans in workspaces that are connected to that pull request's destination branch.

  The destination branch is the branch that a pull request proposes to make changes to; this is often the repository's main branch, but not always.

- If a workspace is configured to only treat certain directories in a repository as relevant, pull requests that don't affect those directories won't trigger speculative plans in that workspace. For more information, see [VCS settings: automatic run triggering](/terraform/cloud-docs/workspaces/settings/vcs#automatic-run-triggering).

  -> **Note:** If HCP Terraform skips a plan because the changes weren't relevant, it will still post a passing commit status to the pull request.

- HCP Terraform does not update the status checks on a pull request with the status of an associated apply. This means that a commit with a successful plan but an errored apply will still show the passing commit status from the plan.

### Contents of Pull Request Plans

Speculative plans for pull requests use the contents of the head branch (the branch that the PR proposes to merge into the destination branch), and they compare against the workspace's current state at the time of the plan. This means that if the destination branch changes significantly after the head branch is created, the speculative plan might not accurately show the results of accepting the PR. To get a more accurate view, you can rebase the head branch onto a more recent commit, or merge the destination branch into the head branch.

## Testing Terraform Upgrades with Speculative Plans

You can start a new [speculative plan][speculative plan] in the UI with the workspace's current configuration version and any Terraform version available to the organization.

1. Click **+ New run**.
1. Select **Plan only** as the run type.
1. Select a version from the **Choose Terraform version** menu. The speculative plan will use this version without changing the workspace's settings.
1. Click **Start run**.

If the run is successful, you can change the workspace's Terraform version and [upgrade the state](/terraform/cloud-docs/workspaces/state#upgrading-state).

## Speculative Plans During Development

You can also use the CLI to run speculative plans on demand before making a pull request. Refer to the [CLI-driven run workflow](/terraform/cloud-docs/run/cli#remote-speculative-plans) for more details.

page title  UI VCS driven Runs   Runs   HCP Terraform description       Workspaces are associated with a VCS repository branch  and HCP Terraform   automatically queues runs when new commits are merged         The UI  and VCS driven Run Workflow  HCP Terraform has three workflows for managing Terraform runs     The UI VCS driven run workflow described below  which is the primary mode of operation    The  API driven run workflow   terraform cloud docs run api   which is more flexible but requires you to create some tooling    The  CLI driven run workflow   terraform cloud docs run cli   which uses Terraform s standard CLI tools to execute runs in HCP Terraform      Summary  In the UI and VCS workflow  every workspace is associated with a specific branch of a VCS repo of Terraform configurations  HCP Terraform registers webhooks with your VCS provider when you create a workspace  then automatically queues a Terraform run whenever new commits are merged to that branch of workspace s linked repository   HCP Terraform also performs a  speculative plan    when a pull request is opened against that branch  HCP Terraform posts a link to the plan in the pull request  and re runs the plan if the pull request is updated    speculative plan    terraform cloud docs run remote operations speculative plans  The Terraform code for a normal run always comes from version control  and is always associated with a specific commit      Automatically Starting Runs  In a workspace linked to a VCS repository  runs start automatically when you merge or commit changes to version control   If you use GitHub as your VCS provider and merge a PR changing 300 or more files  HCP Terraform automatically triggers runs for every workspace connected to that repository  The GitHub API has a limit of 300 reported changed files for a PR merge  To address this  HCP Terraform initiates workspace runs proactively  preventing oversight of file changes beyond this limit   A workspace is linked to one branch of a VCS repository and ignores changes to other branches  You can specify which files and directories within your repository trigger runs  HCP Terraform can also automatically trigger runs when you create Git tags  Refer to  Automatic Run Triggering   terraform cloud docs workspaces settings vcs automatic run triggering  for details        Note    A workspace with no runs will not accept new runs via VCS webhook  At least one run must be manually queued to confirm that the workspace is ready for further runs   A workspace will not process a webhook if the workspace previously processed a webhook with the same commit SHA and created a run  To trigger a run  create a new commit  If a workspace receives a webhook with a previously processed commit  HCP Terraform will add a new event to the  VCS Events   terraform cloud docs vcs viewing events  page documenting the received webhook      Manually Starting Runs  You can manually trigger a run using the UI  Manual runs let you apply configuration changes when you update variable values but the configuration in version control is unchanged  You must manually trigger an initial run in any new VCS driven workspace   To start a run  click the     New run   button on the workspace page  This opens a   Start a new run   dialog  Select the run mode and provide an optional message  Review the  run modes documentation   terraform cloud docs run modes and options  for more detail on supported options   Run modes that have a plan phase support debugging mode  This is equivalent to setting the  TF LOG  environment variable to  TRACE  for this run only  To enable debugging  click   Additional planning options   under the run mode and click   Enable debugging mode     See  Debugging Terraform   terraform internals debugging  for more information   To  replace   terraform cloud docs run modes and options replacing selected resources  specific resources as part of a standard plan and apply run  expand the   Additional planning options   section and select the resources to replace   Manually starting a run requires permission to queue plans for the workspace    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers  If the workspace has a plan that is still in the  plan stage   terraform cloud docs run states the plan stage  when a new plan is queued  you can either wait for it to complete  or visit the   Current Run   page and click   Run this plan now    Be aware that this action terminates the current plan and unlocks the workspace  which can lead to anomalies in behavior  but can be useful if the plans are long running and the current plan does not have all the desired changes      Automatically cancel plan only runs triggered by outdated commits  Refer to  Automatically cancel plan only runs triggered by outdated commits   terraform cloud docs users teams organizations organizations vcs speculative plan management  for additional information      Confirming or Discarding Plans  By default  run plans require confirmation before HCP Terraform will apply them  Users with permission to apply runs for the workspace can navigate to a run that has finished planning and click the  Confirm   Apply  or  Discard Plan  button to finish or cancel a run    More about permissions    terraform cloud docs users teams organizations permissions   If necessary  use the  View Plan  button for more details about what the run will change    permissions citation    intentionally unused   keep for maintainers    confirm button   img docs runs confirm png   Users can also leave comments if there s something unusual involved in a run   Note that once the plan stage is completed  until you apply or discard a plan  HCP Terraform can t start another run in that workspace       Auto apply  If you would rather automatically apply plans that don t have errors  you can  enable auto apply   terraform cloud docs workspaces settings auto apply and manual apply  on the workspace s  General Settings  page  Some plans can t be auto applied  like plans queued by  run triggers   terraform cloud docs workspaces settings run triggers  or by users without permission to apply runs    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers     Speculative Plans on Pull Requests  To help you review proposed changes  HCP Terraform can automatically run  speculative plans  speculative plan  for pull requests or merge requests       Viewing Pull Request Plans  You can view speculative plans in a workspace s list of normal runs  Additionally  HCP Terraform adds a link to the run in the pull request itself  along with an indicator of the run s status   A single pull request can include links to multiple plans  depending on how many workspaces connect to the destination branch  If you update a pull request  HCP Terraform performs new speculative plans and update the links   Although any contributor to the repository can see the status indicators for pull request plans  only members of your HCP Terraform organization with permission to read runs for the affected workspaces can click through and view the complete plan output    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers      Rules for Triggering Pull Request Plans  Whenever a pull request is  created or updated   HCP Terraform checks whether it should run speculative plans in workspaces connected to that repository  based on the following rules     Only pull requests that originate from within the same repository can trigger speculative plans     To avoid executing malicious code or exposing sensitive information  HCP Terraform doesn t run speculative plans for pull requests that originate from forks of a repository          Note    On Terraform Enterprise  administrators can choose to allow speculative plans on pull requests that originate from forks  To learn more about this setting  refer to the  general settings documentation   terraform enterprise admin application general allow speculative plans on pull requests from forks     Pull requests can only trigger runs in workspaces where automatic speculative plans are allowed  You can  disable automatic speculative plans   terraform cloud docs workspaces settings vcs automatic speculative plans  in a workspace s VCS settings     A pull request will only trigger speculative plans in workspaces that are connected to that pull request s destination branch     The destination branch is the branch that a pull request proposes to make changes to  this is often the repository s main branch  but not always     If a workspace is configured to only treat certain directories in a repository as relevant  pull requests that don t affect those directories won t trigger speculative plans in that workspace  For more information  see  VCS settings  automatic run triggering   terraform cloud docs workspaces settings vcs automatic run triggering           Note    If HCP Terraform skips a plan because the changes weren t relevant  it will still post a passing commit status to the pull request     HCP Terraform does not update the status checks on a pull request with the status of an associated apply  This means that a commit with a successful plan but an errored apply will still show the passing commit status from the plan       Contents of Pull Request Plans  Speculative plans for pull requests use the contents of the head branch  the branch that the PR proposes to merge into the destination branch   and they compare against the workspace s current state at the time of the plan  This means that if the destination branch changes significantly after the head branch is created  the speculative plan might not accurately show the results of accepting the PR  To get a more accurate view  you can rebase the head branch onto a more recent commit  or merge the destination branch into the head branch      Testing Terraform Upgrades with Speculative Plans  You can start a new  speculative plan  speculative plan  in the UI with the workspace s current configuration version and any Terraform version available to the organization   1  Click     New run    1  Select   Plan only   as the run type  1  Select a version from the   Choose Terraform version   menu  The speculative plan will use this version without changing the workspace s settings  1  Click   Start run     If the run is successful  you can change the workspace s Terraform version and  upgrade the state   terraform cloud docs workspaces state upgrading state       Speculative Plans During Development  You can also use the CLI to run speculative plans on demand before making a pull request  Refer to the  CLI driven run workflow   terraform cloud docs run cli remote speculative plans  for more details