Skip to content

VCS Providers

To connect workspaces and modules to git repositories containing Terraform configurations, you need to provide OTF with access to your VCS provider. You have a choice of three providers:

  • Github app
  • Github personal access token
  • Gitlab personal access token


This walkthrough shows you how to create a VCS provider via the web UI.

On your organization's main menu, select VCS providers.

organization main menu

You are presented with a choice of providers to create:

vcs providers list

In this walkthrough we will create a provider using a Github personal access token.

Select New Github VCS Provider (Personal Token). You are then presented with a form on which to enter the token:

new github vcs provider form

Click the personal token link. It'll take you to Github where you can create the token. Create a classic token with the repo scope (or you can create a fine-tuned token with the equivalent permissions). The token permits OTF to access your git repository and retrieve terraform configuration. Once you've generated the token, copy and paste it into the Token field. Optionally you can also assign the provider a name.

Create the provider and it'll appear on the list of providers:

vcs providers list

You can now proceed to connecting workspaces (see below) and publishing modules.

Connecting a workspace

Once you have a provider you can connect a workspace to a git repository for that provider.

Select a workspace. Go to settings.

workspace main page

Click Connect to VCS.

workspace settings

Select the provider.

workspace vcs providers list

You'll then be presented with a list of repositories. Select the repository containing the terraform configuration you want to use in your workspace. If you cannot see your repository you can enter its name.

workspace vcs repo list

Once connected you can start a run via the web UI. On the workspace page select the start run drop-down box and select an option to either start a plan or both a plan and an apply.

connected workspace main page

That will start a run, retrieving the configuration from the repository, and you will see the progress of its plan and apply.

run page started