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, which is more flexible but requires you to create some tooling.
• The CLI-driven run workflow, 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.

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 for details.

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 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 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 for more information.

To replace 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.)

If the workspace has a plan that is still in 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 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.) If necessary, use the "View Plan" button for more details about what the run will change.

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 on the workspace's "General Settings" page. Some plans can't be auto-applied, like plans queued by run triggers or by users without permission to apply runs. (More about permissions.)

Speculative Plans on Pull Requests

To help you review proposed changes, HCP Terraform can automatically run speculative plans 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.)

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

• Pull requests can only trigger runs in workspaces where automatic speculative plans are allowed. You can disable 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.

  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 in the UI with the workspace's current configuration version and any Terraform version available to the organization.

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

If the run is successful, you can change the workspace's Terraform version and upgrade the 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 for more details.