Configure GitHub.com access through OAuth

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

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

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

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

Prerequisites

For this tutorial, you will need:

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

On HCP Terraform, add a new VCS Provider

Open HCP Terraform in your browser and navigate to your organization settings. Then, select Version Control | Providers from the left navigation.

Click the Add a VCS Provider button. Select GitHub then GitHub.com (Custom) from the dropdown.

The next page includes instructions to set up your provider by registering a new 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 HCP Terraform "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 HCP Terraform VCS provider.

On HCP Terraform, 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 HCP Terraform app against GitHub by clicking the green "Authorize <GITHUB_USER>" button.

Your browser will return to HCP Terraform. On the Advanced Settings step, you can optionally restrict this VCS provider to selected projects, configure policy sets, modules, and an SSH keypair.

Click "Skip and finish" to finish adding a VCS provider to your HCP Terraform organization.

Next steps

You have successfully configured your HCP Terraform 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.