Create a Workspace

In this tutorial, you will create a version control system (VCS) driven Terraform Cloud workspace by connecting a sample repository to Terraform Cloud. This Terraform Cloud workspace will provision an AWS EC2 instance.


While Terraform can provision resources on many different providers and connect with several popular version control systems (VCSs), this tutorial requires:

Fork a Github repository

Visit this example GitHub repository, which contains the Terraform configuration for an EC2 instance.

Click the “Fork” button at the top right of the page to copy the repository to your GitHub account.

Use the fork button; do not clone

Explore your fork of the repository. It contains Terraform configuration files, which define and expose information about your infrastructure:

  • specifies the AWS provider, a provider plugin that connects Terraform Cloud to the AWS API, and the random provider, another provider that will generate the random name for the table. It also defines resources that represent the table name and the table itself, with the information that AWS needs to know about the table’s settings.
  • defines the input variables that are referenced in, which make the configuration easy to customize and collaborate on. You will set some of these values in the Terraform Cloud UI later on in this tutorial.
  • defines the information about your infrastructure that Terraform Cloud will display to you when it makes changes.
  • defines version constraints for Terraform, the AWS provider, and the random provider.

Connect Terraform Cloud to GitHub

Navigate to the “Workspaces” page from the main menu and click ”+ New workspace”

Create a new Terraform Cloud Workspace

On the “New Workspace” page, select the “Version control workflow” from the workflow options screen. On the “Connect to VCS” screen, press the “GitHub” button and then choose “ (Custom)” from the drop-down to continue.

New workspace

A new window will open asking you to authorize Terraform Cloud to use your GitHub account. Click the green “Authorize” button to connect Terraform Cloud to your GitHub account.

GitHub Authorization

You may be asked to install Terraform Cloud for your GitHub account or organization. If prompted, select your account or organization to install Terraform Cloud.

Install Terraform Cloud

For information about installing Terraform Cloud on GitHub, refer to the Terraform Documentation: Configuration-Free GitHub Usage.

Choose a repository

Next, Terraform will display a list of your GitHub repositories. Choose the repository you forked, called “tfc-guide-example”. If you have many GitHub repositories, you may need to filter the list to find the correct one.

Connect VCS repository to Terraform Cloud Workspace

Create the workspace

On the next screen, leave the workspace name and “Advanced options” unchanged, and click the purple “Create workspace” button to create the workspace.

Configure settings

It will take a few minutes for Terraform Cloud to connect to your GitHub repository. Once connected, Terraform Cloud will display a notification that your configuration was uploaded successfully.

Terraform Cloud new workspace landing page

Next Steps

In this tutorial, you created a workspace and connected it to your GitHub repository. Read more about Terraform Cloud workspaces in the documentation.

Next, you will configure your new workspace with variables and provision your infrastructure by queuing a run in Terraform Cloud.