VCS Integrated Workspace

VCS Integrated Workspace

Scalr workspaces can be linked to Terraform configuration files held in VCS repositories in order to automate pull request (PR) checks and deployments.

By linking a workspace to a specific branch of the repository a webhook is created in the VCS provider that will POST to Scalr for every PR or commit/merge that affects that branch. Scalr will then automatically perform a “dry run” (terraform plan) for every PR and a run (terraform apply) for every commit/merge.

Create Workspace

To enable a VCS based workspace, create a workspace linked to a specific repo and branch:


Workspaces can be updated with the following settings:

  • Branch - The branch of the repository that the workspace should point to.

  • Terraform Working Directory - This is where Terraform actually runs. This directory must be a subdirectory of the top level of the repository or of the subdirectory if specified.

  • Triggers - If there are multiple folders, other than just the working directory, that need to trigger a run based on a change. Trigger prefixes require a working directory to be set. And that working directory is always a trigger prefix.

At this point, a run can be triggered, but if your configuration requires variables to be set, there will be a prompt for that.

  • Variable Files - It is best practice to create Terraform code in a reusable manner, which is where variable files help. Set the path to the variable file if it is located in the same repository. The variable file location is absolute to the repository root and is not relative to a working directory of a workspace.



If you would prefer that a run is not started based on a VCS commit or PR, add [skip ci] in the first line of a head commit message. Users will still be able to queue runs manually if the configuration version is associated with a commit with the skip tag.

Set Terraform Variables

Terraform variables can be set in the Terraform code or within the Scalr UI. If the configuration contains variables that do not have assigned values, then these must be assigned values in then Scalr workspace via the UI. Scalr will automatically create the variables.


If the local workspace contains any *.auto.tfvars files these will provide default variable values that Terraform will automatically use.

If variables in the *.auto.tfvars files have the same names as variables specified in the workspace, the predefined workspace values will be used. For map variables the values in *.auto.tfvars are merged with values in the same named variable in the workspace.

If the Terraform configuration utilizes shell variables (export var=value), e.g. for credentials or to set values for Terraform input variables with TF_VAR_{variable_name}={value} (-parallelism, -var-file, etc).

Shell variables can be set at all levels in Scalr and are inherited by lower levels. Use environment or account level for shell variables that are needed in multiple workspaces or environments. Use workspace level for shell variables that are specific to individual Terraform configurations.

It is also possible to use the Scalr provider to pull output from one workspace and post it as an environment or account shell variable to make it easily available to all other workspaces.


See Variables for full details.


More of a visual learner? Check out this feature on YouTube.