April 6 & 7
Learn about Vault, Consul, & more at HashiDays Sydney in Australia Register Now

Terraform Cloud

Configuring Version Control Access with Terraform Cloud - GitHub

Prerequisites: At this point, you should have gotten access to Terraform Cloud, and created an organization if necessary.

Before you can use Terraform Cloud, it needs access to the version control system (VCS) you use for Terraform code.

About VCS Access

Most workspaces in Terraform Cloud are associated with a VCS repository, which provides Terraform configurations for that workspace. To find out which repos are available, access their contents, and create webhooks, Terraform Cloud needs access to your VCS service.

Although Terraform Cloud's API lets you create workspaces and push configurations to them without a VCS connection, the primary workflow expects every workspace to be backed by a repository. If you plan to use Terraform Cloud's GUI to create workspaces, you must configure VCS access first.

Configuring GitHub Access

Connecting Terraform Cloud to your VCS involves five steps:

On your VCSOn TFC
Register your TFC organization as a new app. Get ID and key. 
 Tell TFC how to reach VCS, and provide ID and key. Get callback URL.
Provide callback URL. 
 Request VCS access.
Approve access request. 

The rest of this page explains the GitHub versions of these steps.

Step 1: On GitHub, Create a New OAuth Application

  1. Open github.com in your browser and log in as whichever account you want Terraform Cloud to act as. For most organizations this should be a dedicated service user, but a personal account will also work.

  2. Navigate to GitHub's Register a New OAuth Application page.

    This page is located at https://github.com/settings/applications/new. You can also reach it through GitHub's menus:

    1. In the upper right corner, click your profile picture and choose "Settings."
    2. In the navigation sidebar, click "Developer settings," then make sure you're on the "OAuth Apps" page (not "GitHub Apps").
    3. In the upper right corner, click the "New OAuth App" button.
  3. This page has a form with four text fields.

    GitHub screenshot: New OAuth application fields

    Fill them in as follows:

    Field nameValue
    Application NameTerraform Cloud (<YOUR ORGANIZATION NAME>)
    Homepage URLhttps://app.terraform.io (or the URL of your private TFC install)
    Application DescriptionAny description of your choice.
    Authorization callback URLhttps://example.com/replace-this-later (or any placeholder; the correct URI doesn't exist until the next step.)
  4. Click the "Register application" button, which creates the application and takes you to its page.

  5. Download this image of the Terraform logo, upload it with the "Upload new logo" button or the drag-and-drop target, and set the badge background color to `#5C4EE5`. This optional step helps you identify Terraform Cloud's pull request checks at a glance.
  6. Leave this page open in a browser tab. In the next step, you will copy and paste the unique Client ID and Client Secret.

    GitHub screenshot: the new application's client ID and client secret

Step 2: On Terraform Cloud, Add a VCS Provider

  1. Open Terraform Cloud in your browser and navigate to the "VCS Provider" settings for your organization. Click the "Add VCS Provider" button.

    If you just created your organization, you might already be on this page. Otherwise:

    1. Click the upper-left organization menu, making sure it currently shows your organization.
    2. Click the "Settings" link at the top of the page (or within the menu)
    3. On the next page, click "VCS Provider" in the left sidebar.
    4. Click the "Add VCS Provider" button.
  2. The next page has a drop-down and four text fields. Select "GitHub.com" from the drop-down, and enter the Client ID and Client Secret from the previous step. (Ignore the two disabled URL fields, which are used for on-premise VCSs.)

    Terraform Cloud screenshot: add client fields

  3. Click "Create VCS Provider." This will take you back to the VCS Provider page, which now includes your new GitHub client.

  4. Locate the new client's "Callback URL," and copy it to your clipboard; you'll paste it in the next step. Leave this page open in a browser tab.

    Terraform Cloud screenshot: callback url

Step 3: On GitHub, Update the Callback URL

  1. Go back to your GitHub browser tab. (If you accidentally closed it, you can reach your OAuth app page through the menus: use the upper right menu > Settings > Developer settings > OAuth Apps > "Terraform Cloud (<YOUR ORG NAME>)".)

  2. In the "Authorization Callback URL" field, near the bottom of the page, paste the callback URL from Terraform Cloud's OAuth Configuration page, replacing the "example.com" placeholder you entered earlier.

  3. Click the "Update application" button. A banner saying the update succeeded should appear at the top of the page.

Step 4: On Terraform Cloud, Request Access

  1. Go back to your Terraform Cloud browser tab and click the "Connect organization <NAME>" button on the VCS Provider page.

    Terraform Cloud screenshot: the connect organization button

    This takes you to a page on github.com, asking whether you want to authorize the app.

  2. The authorization page lists any GitHub organizations this account belongs to. If there is a "Request" button next to the organization that owns your Terraform code repositories, click it now. Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization's access restrictions. See About OAuth App access restrictions.

    GitHub screenshot: the authorization screen

  3. Click the green "Authorize <GITHUB USER>" button at the bottom of the authorization page. GitHub might request your password to confirm the operation.

Step 5: Contact Your GitHub Organization Admins

If your organization uses OAuth app access restrictions, you had to click a "Request" button when authorizing Terraform Cloud, which sent an automated email to the administrators of your GitHub organization. An administrator must approve the request before Terraform Cloud can access your organization's shared repositories.

If you're a GitHub administrator, check your email now and respond to the request; otherwise, contact whoever is responsible for GitHub accounts in your organization, and wait for confirmation that they've approved your request.