A Scalr VCS workspace connects your infrastructure as code, managed by Terraform or OpenTofu, to a specific branch in a version control system repository. This integration automates the process of planning and applying infrastructure changes in response to code commits and pull requests.

Set Up

Connect a VCS repository if you haven't already. After selecting VCS as the source, set the following options:

Triggering Event

The triggering event determines what action will create a run when using VCS as the workspace source. There are two events to select from:

• Commit Pushed: Runs are triggered by commits and pull requests. Scalr triggers a run when a pull request is opened or a commit is created for the branch to which the workspace is linked.
• Tag Created: Runs are triggered when a git tag is published and matches the version constraint defined in the workspace settings. Only stable releases trigger runs; unstable releases can be added but do not trigger runs automatically. Automated dry runs are not currently available for tag-based workspaces, but they can be started through the UI, API, or CLI. Version constraint supports version ranges in the Terraform-like style, e.g. ~> 1.0.0, >= 1.0, <= 2.0, etc.

Settings

• VCS Provider - Select the provider that contains the Terraform and OpenTofu repositories.

• Repository - Select the repository where the code resides.

• Terraform Working Directory - This is where Terraform commands are executed. This directory must be a subdirectory of the top level of the repository. This comes in handy in the case of a mono repo.

• Trigger Strategy - The rules in which a run should be triggered based on files or folders being updated.

  • Any Changes - Any change in the repository specified will trigger a run.
  • Trigger Patterns - Use glob patterns to specify which files/directories should initiate a run. Patterns can be used in combination with a working directory, but not with trigger prefixes. For example, if the following patterns were set a run would execute if there were changes inmy/awesome/workdir/ or modules/core/iam/teams, but changes to any .md files would be ignored.

  my/awesome/workdir/
  modules/core/iam/teams
  !*.md

  • Directories - Use a working directory as well as trigger prefixes to trigger a run based on any files being changed in any of the directory paths. Trigger prefixes cannot be used in combination with trigger patterns.

• Trigger a plan-only run when a PR is opened/updated - This is a control mechanism to avoid unwanted dry runs on every commit. This is only available for the "Commit Pushed" triggering event.

• Clone submodules - This allows you to specify whether git submodules should be fetched when cloning a VCS repository.

• Select variable files - This specified which tfvars files should be pulled in from the repository.

• Skipping specific commits - 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. Use [skip scalr ci] to avoid conflict with other CI tools that use the same message.

Pull Requests

For commit-based workspaces, Scalr will execute a dry run (plan-only) upon creating a pull request against the branch the workspace is linked to if the working directory or trigger pattern is affected. Subsequent commits to the pull request will also trigger a dry run regardless of the code changed in the new commit. Scalr evaluates all commits in the pull request on every new push, not just the latest commit.

If the "Send summary back to PR comments" is enabled in the VCS integration settings, Scalr will send plan summaries back to the PR comment:

Alternatively, if "Send run results to pull request checks" is set (GitHub only), a pull request check will display the run results:

Select a Commit Strategy

While this is not a setting in the workspace itself, admins can choose between the following two commit strategies when adding a VCS provider connection. All workspaces that use this VCS connection will inherit this setting:

Head Commit of the Base Branch: The default base commit strategy compares the latest head commit with the base branch commit

Previous Commit of the PR Branch: The commit compares the latest head commit with the previous head commit

The head commit strategy compares ALL commits in the PR every time a commit is pushed, while the previous commit strategy only compares the new commit to the previous commit that was made.

Pull Request Views

The pull request views in each workspace provide a real-time, centralized view of all PRs affecting that workspace. Users can view key details, including PR name, author, run status, and commit information. The list supports sorting, searching by PR ID or commit, and filtering by status. Requires the workspaces:read permission.

Execute a Run from a PR Comment or Check (Atlantis-Style)

From Comments

For VCS-based workspaces, a plan or apply run can be executed directly from a pull request comment. As of right now, GitHub, GitLab, and Azure DevOps are supported. To execute a run from a comment, simply execute the following in a pull request comment:

/scalr plan

or

/scalr apply

The status of the run will be sent back to the VCS provider as a comment:

If the workspace setting "Enabled VCS-driven dry runs" is disabled, the /scalr plan command will not work, but apply will. To override this, use the -force flag to force a plan to execute: /scalr plan -force

Command List:

If the auto-queue run is set to never in the workspace settings, runs will not execute from pull request comments until it is changed to skip first or always. The default value is "Skip first".

Since the apply happens through a comment before the merge, users can avoid another apply executing when the pull request is merged by adding the following to the headcommit message of a pull request:

[skip scalr] or [skip ci]

The ability to execute runs from a comment is controlled through the VCS provider settings:

• Github
• Gitlab
• Azure DevOps

From Checks

Note: Checks are only available for GitHub

Alternatively, runs can be executed directly from a PR check if "Send run results to pull request checks" is enabled. At the top of each check, users can select between "Restart plan" and "Apply":

Avoid State Update by Unmerged PRs

Want to ensure that Terraform state modifications are only applied from the main workspace branch or a verified PR, preventing accidental overwrites or conflicts caused by unmerged changes? 

Scalr safeguards your Terraform state from unintended modifications with branch awareness. Scalr displays warnings when changes are attempted from branches with unmerged pull requests, and automatically prevents auto-apply operations when the state-generating branch differs from your run's configuration branch. This ensures state modifications only occur from your main workspace branch or properly verified pull requests, preventing accidental overwrites and conflicts.

Prevent an Apply from a PR that Cannot be Merged

If you are using the apply before merge workflow, you want to make sure that the /scalr apply command can only be executed after a PR is approved and passes branch protection checks, so you can enforce compliance and prevent unauthorized Terraform changes. This can be done by checking the merge_error attribute in the run input. See more on this here.

Automatic Base Branch Merge Before Run Execution

VCS-driven workspaces can automatically merge the base branch into the head branch before triggering a run. This ensures that runs are always executed against the latest code in the base branch, providing more accurate and reliable results. This helps a common pain point where runs could be executed against outdated head branches, potentially leading to false-positive results or failed applies after merging.

To implement this feature, enable the auto-merge option when configuring the VCS provider:

Approve a Run from a Pull Request

For VCS-based workspaces, an apply run can be approved or declined directly from a pull request comment. GitHub and Azure DevOps are currently supported; other VCS providers will be added soon. To approve or decline a run from a comment, simply execute the following commands in a pull request comment:

A reason can be added to all approvals with the -reason="Your reason here"argument:

/scalr approve -workspace-id=ws-xxxxxxxxx,ws-yyyyyyyyy -reason="Your reason here"

A default Approved from VCS comment message will be added if no reason is given.

Permissions

For a user to be able to approve or decline a run, the following must apply:

• Users must have the same email address in both GitHub or Azure DevOps and Scalr.
• Users must have the runs:apply permission otherwise, the approve or decline commands will not be permitted.

Provider Configurations

Before executing a run in a workspace, credentials must be added so that the code can authenticate to the Terraform provider during the run. This can be done through the Scalr provider configuration feature. Provider configurations give users a central place to manage their configurations and assign them for use within environments and workspaces.

Set Variables

Once the workspace is saved, variables might need to be added to the workspace if required. Find out more about setting shell and Terraform/Tofu variables here.

Execution

A run will execute upon the next commit, pull request, or manual execution of a run. Alternatively, you can set auto-queue run to always, which will automatically start a run upon the workspace being created. Auto queuing of runs is helpful when you automatically create workspaces through the Scalr provider as you can kick off a run in the workspace as soon as it is provisioned via Terraform without manual intervention.

Runs can also be triggered based on users adding a /scalr plan comment to the comments of a pull request.

Extra Settings

There are other optional settings that can be applied to all workspace types which can be found in workspace settings.

VCS Tasks

Overview

VCS Tasks allows you to programmatically trigger Terraform/OpenTofu runs for your VCS-driven workspaces by creating tasks that queue runs from specific commits. This is particularly useful for integrating Scalr with your CI/CD pipelines to trigger infrastructure deployments after completing prerequisite steps such as code validation, testing, building container images, or other deployment preparation tasks.

What are VCS Tasks?

VCS Tasks are API-driven requests that tell Scalr to process a specific commit from a repository and trigger runs for all associated VCS-driven workspaces. When you create a VCS task, Scalr will:

1. Identify VCS-driven workspaces connected to the specified repository
2. Create configuration versions for the specified commit
3. Queue Terraform runs based on workspace settings and changes detected
4. Process runs according to your workspace auto-queue settings

Key Benefits

• Controlled Infrastructure Deployment: Trigger Terraform/OpenTofu runs only after your CI/CD pipeline validates code, runs tests, and completes build processes
• Sequential Deployment Workflow: Ensure infrastructure changes happen at the right time in your deployment pipeline, after application preparation is complete
• Integration Flexibility: Works with any CI/CD system that can make HTTP API calls
• Conditional Triggering: Only execute infrastructure runs when your pipeline determines it's appropriate (e.g., after successful tests, on specific branches, or manual approval)

Prerequisites

Before using VCS Tasks, ensure you have:

1. VCS-driven workspaces configured in Scalr with repository bindings
2. VCS Provider set up and authenticated (GitHub, GitLab, Bitbucket, etc.)
3. Repository access - the repository must be connected to at least one workspace
4. Scalr CLI installed and configured (see installation instructions below)

Scalr CLI Installation

Install via Homebrew (Recommended)

# Add the Scalr tap
brew tap Scalr/scalr

# Install scalr-cli
brew install scalr

Alternative Installation Methods

Linux/macOS (Direct Download):

# Download latest release
SCALR_CLI_LATEST=$(curl -sL https://api.github.com/repos/Scalr/scalr-cli/releases/latest | grep -o 'https://github.com/Scalr/scalr-cli/releases/download/[^"]*linux_amd64.tar.gz')
curl -sL "$SCALR_CLI_LATEST" --output scalr-cli.tar.gz
tar -xzf scalr-cli.tar.gz
sudo mv scalr /usr/local/bin/

Windows: Download the latest Windows release from GitHub Releases

CLI Configuration

Set up your Scalr CLI with your credentials:

# Configure your Scalr hostname and token
export SCALR_HOSTNAME="your-account.scalr.io"
export SCALR_TOKEN="your-api-token"

CLI Reference

Create VCS Task Command

scalr create-vcs-task --repository-id "owner/repo-name" --branch "branch-name" --commit-sha "commit-sha"

Parameters

Example Usage

scalr create-vcs-task \
  --repository-id "myorg/infrastructure-repo" \
  --branch "main" \
  --commit-sha "a1b2c3d4e5f6789012345678901234567890abcd"

Using JSON Input (Alternative)

You can also pipe JSON data to the CLI:

echo '{
  "repository-id": "myorg/infrastructure-repo",
  "branch": "main", 
  "commit-sha": "a1b2c3d4e5f6789012345678901234567890abcd"
}' | scalr create-vcs-task

CI/CD Integration Examples

For detailed CI/CD integration examples with popular platforms, see the separate CI/CD Examples document.

The examples cover:

• GitHub Actions - Multi-job workflow with proper dependencies
• GitLab CI/CD - Multi-stage pipeline with sequential execution
• Azure DevOps Pipelines - Stage-based deployment with conditional logic
• Bitbucket Pipelines - Branch-specific deployment workflows

Each example includes:

• ✅ Test and build stages before infrastructure deployment
• �� Scalr CLI installation and configuration
• �� VCS task creation using simple CLI commands
• ��️ Security best practices for token management
• �� Setup instructions for each platform

Best Practices

1. Error Handling

The Scalr CLI automatically handles errors and provides clear error messages. You can add additional error handling in your scripts:

if ! scalr create-vcs-task --repository-id "${REPO_ID}" --branch "${BRANCH}" --commit-sha "${COMMIT_SHA}"; then
  echo "❌ Failed to create VCS task"
  exit 1
fi
echo "✅ VCS task created successfully"

2. Secure Token Storage

• Store API tokens as secrets in your CI/CD system
• Never commit tokens to your repository
• Use environment variables or credential management systems
• Rotate tokens regularly

3. Repository ID Format

Ensure the repository-id matches the format expected by your VCS provider:

• GitHub/GitLab: owner/repository-name
• Bitbucket: workspace/repository-name
• Azure DevOps: organization/project/repository-name

4. Branch and Commit Validation

• Use full 40-character commit SHAs
• Ensure the branch exists and contains the specified commit
• Handle both push and pull request events appropriately

5. CLI Installation Options

• Homebrew (Recommended): for easy installation and updates
• Direct Download: Use the installation scripts provided in the examples for CI/CD environments
• Version Pinning: Consider pinning to specific CLI versions in production pipelines

6. Workspace Configuration

• Ensure your workspaces have appropriate auto-queue-runs setting. It has to be set to Never.
• Configure trigger patterns and prefixes to control when runs execute
• Test with a staging environment first

Troubleshooting

Common Issues

404 - VCS-driven workspaces not found

Cause: No workspaces are connected to the specified repository Solution:

• Verify repository ID format matches your VCS provider
• Check that workspaces exist with VCS bindings to this repository
• Ensure the API token has access to the account containing the workspaces

409 - Task already exists

Cause: A task with the same parameters is already being processed Solution:

• Wait for the existing task to complete
• Check if multiple CI/CD jobs are triggering simultaneously
• Implement retry logic with exponential backoff

Authentication failed

Cause: Invalid or expired API token Solution:

• Verify the API token is correct and not expired
• Ensure SCALR_HOSTNAME and SCALR_TOKEN environment variables are set correctly
• Test CLI configuration: scalr get-accounts

Invalid parameters

Cause: Invalid command parameters Solution:

• Ensure commit SHA is exactly 40 characters
• Validate branch name format
• Check repository ID format matches your VCS provider
• Use scalr -help create-vcs-task for parameter reference

Debugging Tips

1. Test CLI locally before implementing in CI/CD: scalr -help create-vcs-task
2. Enable verbose output with --verbose flag: scalr --verbose create-vcs-task ...
3. Check CLI configuration: scalr -configure to create a new configuration file.
4. Verify workspace settings for auto-queue behavior in Scalr UI.
5. Monitor run queue in Scalr UI to confirm runs are being triggered.
6. Check CLI version: scalr -version. It has to be at least 0.17.0.