Set up the GitHub.com OAuth VCS provider

These instructions are for using GitHub.com for HCP Terraform's VCS features, using a per-organization OAuth connection with the permissions of one particular GitHub user. GitHub Enterprise has separate instructions, as do the other supported VCS providers.

For new users on HCP Terraform, we recommend using our configuration-free GitHub App to access repositories instead.

For Terraform Enterprise site admins, you can create your own GitHub App to access repositories.

Configuring a new VCS provider requires permission to manage VCS settings for the organization. (More about permissions.)

Connecting HCP Terraform to your VCS involves four steps:

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

Step 1: On HCP Terraform, begin adding a new VCS provider

1. Go to your organization's settings and then click Providers in the Version Control section. The VCS Providers page appears.

2. Click Add a VCS provider. The Add VCS Provider page appears.

3. Select GitHub and then select GitHub.com (Custom) from the menu. The page moves to the next step.

Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform.

Step 2: On GitHub, create a new OAuth application

On the HCP Terraform Add VCS Provider page, click register a new OAuth Application. This opens GitHub.com in a new browser tab with the OAuth application settings pre-filled.

Alternately, create the OAuth application manually on GitHub.com.

Manual steps

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

   Important: The account you use for connecting HCP Terraform must have admin access to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions.

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:

   • Click your profile picture and choose "Settings."
   • Click "Developer settings," then make sure you're on the "OAuth Apps" page (not "GitHub Apps").
   • Click the "New OAuth App" button.

3. This page has a form with four text fields.

   Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard.

   Fill out the text fields as follows:

   Field name	Value
   Application Name	HCP Terraform (<YOUR ORGANIZATION NAME>)
   Homepage URL	https://app.terraform.io (or the URL of your Terraform Enterprise instance)
   Application Description	Any description of your choice.
   Authorization callback URL	https://app.terraform.io/<YOUR CALLBACK URL>

Register the OAuth application

1. Click the "Register application" button, which creates the application and takes you to its page.

2. Download this image of the HCP Terraform logo and upload it with the "Upload new logo" button or the drag-and-drop target. This optional step helps you identify HCP Terraform's pull request checks at a glance.

3. Click the Generate a new client secret button. You will need this secret in the next step.

4. Leave this page open in a browser tab. In the next step, you will copy and paste the unique Client ID and Client Secret.

Step 3: On HCP Terraform, set up your provider

1. Enter the Client ID and Client Secret from the previous step, as well as an optional Name for this VCS connection.

2. Click "Connect and continue." This takes you to a page on GitHub.com, asking whether you want to authorize the app.

3. 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.

4. Click the green "Authorize <GITHUB USER>" button at the bottom of the authorization page. GitHub might request your password or multi-factor token to confirm the operation.

Step 4: On HCP Terraform, configure advanced settings (optional)

The settings in this section are optional. The Advanced Settings you can configure are:

• Scope of VCS Provider - You can configure which workspaces can use repositories from this VCS provider. By default the All Projects option is selected, meaning this VCS provider is available to be used by all workspaces in the organization.
• Set up SSH Keypair - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time.

If you don't need to configure advanced settings:

1. Click the Skip and finish button. This returns you to HCP Terraform's VCS Providers page, which now includes your new GitHub client.

If you need to limit the scope of this VCS provider:

1. Select the Selected Projects option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider.

2. Click the Update VCS Provider button to save your selections.

If you need an SSH keypair:

Important notes

• SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS.
• Do not use your personal SSH key to connect HCP Terraform and GitHub; generate a new one or use an existing key reserved for service access.
• In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitHub.
• Protect this private key carefully. It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them.

1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to GitHub.com. The exact command depends on your OS, but is usually something like: ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise" This creates a service_terraform file with the private key, and a service_terraform.pub file with the public key. This SSH key must have an empty passphrase. HCP Terraform cannot use SSH keys that require a passphrase.

2. While logged into the GitHub.com account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created.

3. In HCP Terraform's Add VCS Provider page, paste the text of the SSH private key you just created, and click the Add SSH Key button.

Step 5: Contact your GitHub organization admins

If your organization uses OAuth app access restrictions, you had to click a Request button when authorizing HCP Terraform, which sent an automated email to the administrators of your GitHub organization. An administrator must approve the request before HCP Terraform 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.

Finished

At this point, GitHub access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared GitHub repositories.