• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Home

Terraform Cloud

Skip to main content
  • Terraform Cloud

  • Overview
  • Plans and Features
  • Getting Started
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
  • Migrating to Terraform Cloud

  • Terraform Cloud Agents

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Terraform Cloud
  4. Connecting to VCS
  5. GitHub Enterprise

»Configuring GitHub Enterprise Access

These instructions are for using an on-premise installation of GitHub Enterprise for Terraform Cloud's VCS features. GitHub.com has separate instructions, as do the other supported VCS providers.

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

Connecting Terraform Cloud to your VCS involves four steps:

On your VCSOn Terraform Cloud
 Create a new connection in Terraform Cloud. Get callback URL.
Register your Terraform Cloud organization as a new app. Provide callback URL. Get ID and key. 
 Provide Terraform Cloud with ID and key. Request VCS access.
Approve access request. 

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

Important: Terraform Cloud needs to contact your GitHub Enterprise instance during setup and during normal operation. For the SaaS version of Terraform Cloud, this means GitHub Enterprise must be internet-accessible; for Terraform Enterprise, you must have network connectivity between your Terraform Enterprise and GitHub Enterprise instances.

Note: Alternately, you can 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.

Step 1: On Terraform Cloud, Begin Adding a New VCS Provider

  1. Go to your organization's settings and then click Providers. The VCS Providers page appears.

  2. Click Add VCS Provider. The VCS Providers page appears.

  3. Select GitHub and then select GitHub Enterprise from the menu. The page moves to the next step.

  4. In the "Set up provider" step, fill in the HTTP URL and API URL of your GitHub Enterprise instance, as well as an optional Name for this VCS connection.

    FieldValue
    HTTP URLhttps://<GITHUB INSTANCE HOSTNAME>
    API URLhttps://<GITHUB INSTANCE HOSTNAME>/api/v3

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 Terraform Cloud.

Step 2: On GitHub, Create a New OAuth Application

  1. In a new browser tab, open your GitHub Enterprise instance 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.

    Important: The account you use for connecting Terraform Cloud 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 INSTANCE HOSTNAME>/settings/applications/new. You can also reach it through GitHub's menus:

    • Click your profile picture and choose "Settings."
    • Click "OAuth Apps" (under the "Developer settings" section).
    • Click the "Register a new application" button.
  3. This page has a form with four text fields.

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

    GitHub screenshot: New OAuth application fields

    Fill out the text fields as follows:

    Field nameValue
    Application NameTerraform Cloud (<YOUR ORGANIZATION NAME>)
    Homepage URLhttps://app.terraform.io (or the URL of your Terraform Enterprise instance)
    Application DescriptionAny description of your choice.
    Authorization callback URLhttps://app.terraform.io/<YOUR CALLBACK URL>
  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 3: On Terraform Cloud, Set up Your Provider

  1. Enter the Client ID and Client Secret from the previous step.

  2. Click "Connect and continue." This takes you to a page on your GitHub Enterprise instance, 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.

    GitHub screenshot: the authorization screen

    If it results in a 500 error, it usually means Terraform Cloud was unable to reach your GitHub Enterprise instance.

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

Step 4: On Terraform Cloud, Set Up SSH Keypair (Optional)

Most organizations will not need to add an SSH private 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 private key at a later time.

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 Terraform Cloud and GitHub Enterprise; generate a new one or use an existing key reserved for service access.
  • In the following steps, you must provide Terraform Cloud with the private key. Although Terraform Cloud does not display the text of the key to users after it is entered, it retains it and will use it for authenticating to GitHub Enterprise.
  • 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.

If You Don't Need an SSH Keypair:

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

If You Do Need an SSH Keypair:

  1. On a secure workstation, create an SSH keypair that Terraform Cloud can use to connect to Bitbucket Cloud. 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. Terraform Cloud cannot use SSH keys that require a passphrase.

  2. While logged into the GitHub Enterprise account you want Terraform Cloud 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 Terraform Cloud'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 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.

Finished

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

Edit this page on GitHub

On this page

  1. Configuring GitHub Enterprise Access
  2. Step 1: On Terraform Cloud, Begin Adding a New VCS Provider
  3. Step 2: On GitHub, Create a New OAuth Application
  4. Step 3: On Terraform Cloud, Set up Your Provider
  5. Step 4: On Terraform Cloud, Set Up SSH Keypair (Optional)
  6. Step 5: Contact Your GitHub Organization Admins
  7. Finished
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)