Run triggers

Hands-on: Try the Connect Workspaces with Run Triggers tutorial.

HCP Terraform provides a way to connect your workspace to one or more workspaces within your organization, known as "source workspaces". These connections, called run triggers, allow runs to queue automatically in your workspace on successful apply of runs in any of the source workspaces. You can connect each workspace to up to 20 source workspaces.

Run triggers are designed for workspaces that rely on information or infrastructure produced by other workspaces. If a Terraform configuration uses data sources to read values that might be changed by another workspace, run triggers let you explicitly specify that external dependency.

Viewing and Managing Run Triggers

To add or delete a run trigger, navigate to the desired workspace and choose "Run Triggers" from the "Settings" menu:

This takes you to the run triggers settings page, which shows any existing run triggers. Configuring run triggers requires admin access to the workspace. (More about permissions.) Admins are able to delete any of their workspace’s run triggers from this page.

Creating a Run Trigger

Creating run triggers requires admin access to the workspace. You must also have permission to read runs for the source workspace you wish to connect to. (More about permissions.)

Under the "Source Workspaces" section, select the workspace you would like to connect as your source and click "Add workspace". You now have a run trigger established with your source workspace. Any run from that source workspace which applies successfully will now cause a new run to be queued in your workspace.

Run Triggers Auto-Apply Setting

Runs initiated by a run trigger do not auto-apply unless you enable the Auto-apply run triggers setting. This setting operates independently of the primary workspace auto-apply setting.

Interacting with Run Triggers

Runs which are queued in your workspace through a run trigger will include extra information in their run details section. This includes links to the source workspace and the successfully applied run that activated the run trigger.

The source workspace includes a message in the plan and apply run details that specifies the workspaces where HCP Terraform automatically starts a run.

Using a Remote State Data Source

A common way to share information between workspaces is the terraform_remote_state data source, which allows a Terraform configuration to access a source workspace's root-level outputs.

Before other workspaces can read the outputs of a workspace, it must be configured to allow access. For more information about cross-workspace state access in HCP Terraform, see Terraform State in HCP Terraform.