Configure GitHub.com Access through OAuth

Terraform Cloud is more powerful when you integrate it with your version control system (VCS). There are three different ways to connect GitHub.com to Terraform Cloud.

1. Our configuration-free GitHub App — we recommend this method for beginning users on Terraform Cloud.
2. Configuring GitHub.com access to Terraform Cloud through OAuth connection — use this method to manage your Terraform Cloud workspaces via the TFE Provider or Terraform Cloud API.
3. Skip the OAuth configuration process and authenticate with a personal access token. This requires using Terraform Cloud's API. For details, see the OAuth Clients API page.

In this tutorial, you will set up GitHub.com OAuth access to Terraform Cloud by completing the following three steps.

1. On Terraform Cloud, add a new VCS Provider
2. On GitHub, create a new OAuth application
3. On Terraform Cloud, set up your provider

Prerequisites

For this tutorial, you will need:

1. a Terraform Cloud with permission to manage VCS settings for the organization
2. a GitHub account

On Terraform Cloud, add a new VCS Provider

Open Terraform Cloud in your browser and navigate to your organization settings. Then, select "VCS Providers".

Click the "Add VCS Provider" button. Select "GitHub" then "GitHub.com (Custom)" from the dropdown. You should be taken to a page with instructions to create and configure an GitHub OAuth application.

On GitHub, create a new OAuth application

In a new browser tab, open GitHub's Register a New OAuth Application page.

Fill out the text fields with the values from the Terraform Cloud "Add VCS Provider" page. Then, click "Register application".

GitHub should return a Client ID and Client Secret. You will use these values to set up your Terraform Cloud VCS provider.

On Terraform Cloud, set up your provider

Navigate to the tab you used to create a new VCS provider.

Enter the Client ID and Client Secret from the previous step to finish setting up your VCS provider. Click "Connect and continue".

This takes you to a page on GitHub.com, asking whether you want to authorize the app. Authorize the Terraform Cloud app against GitHub by clicking the green "Authorize <GITHUB_USER>" button.

The VCS provider will ask you to set up an SSH keypair. This is an optional step. Click "Skip and finish" to finish adding a VCS provider to your Terraform Cloud organization.

Next steps

You have successfully configured your Terraform Cloud organization to access GitHub.com through OAuth connection.

If you had trouble setting up GitHub OAuth, in-depth instructions can be found on the Configuring GitHub.com Access (OAuth) documentation page.