HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Terraform
Terraform Home

Integrate with a GitHub App

This topic describes how to integrate your Terraform Enterpise deployment with a GitHub App.

Introduction

Site administrators can provision a GitHub App integration that all organizations on the same Terraform Enterprise instance can use to access GitHub repositories. Integrating with a GitHub App offers advantages over connecting to GitHub repositories using GitHub OAuth. Refer to GitHub Documentation to learn more.

Configuring GitHub App Integration

These instructions are for using repositories from GitHub.com or Self-hosted GitHub Enterprise with Terraform Enterprise.

For more information on using a GitHub App and GitHub Permissions in HCP Terraform, see GitHub Permissions in HCP Terraform.

Step 1: Configure GitHub App Settings in Terraform Enterprise

You can integrate with either GitHub.com or a self-hosted GitHub Enterprise instance.

  1. Go to the admin interface and then click VCS Integrations. The VCS Integrations page appears.

  2. Click Create global GitHub App. The Location and GitHub App Owner options appear.

  3. For the Location option, choose if you want to integrate with GitHub.com or a Self-hosted GitHub Enterprise instance.

    • If integrating with a Self-hosted GitHub Enterprise instance, fill in the HTTP URL and API URL of your GitHub Enterprise instance.
    FieldValue
    HTTP URLhttps://<GITHUB INSTANCE HOSTNAME>
    API URLhttps://<GITHUB INSTANCE HOSTNAME>/api/v3

  4. For the GitHub App Owner, choose either Personal Account or Organization Account.

    • If assigning ownership to a GitHub Organization, fill in the Organization Name.

    Note: You can change this later. See the Transferring GitHub App Ownership section below for more information.

  5. Click Create global GitHub App. You will be redirected to the Create GitHub App screen on GitHub.

  6. Modify the default GitHub App name if necessary. When done, click Create GitHub App for [GitHub User Handle].

Note: The GitHub App name must satisfy GitHub's requirements.

Step 2: Authorize and Install the GitHub App

In order to start using your GitHub App, you must authorize and install it.

  1. Click Authorize. The GitHub Authorization dialog appears.

  2. Accept the authorization. Afterwards, the GitHub installation dialog will appear.

    Note: If the installation dialog fails to appear, make sure your browser settings allow pop-ups for your Terraform Enterprise site.

  3. Select the repositories you want to grant access to.

Note: This will limit which GitHub repositories your workspaces, policy sets, and registry modules have access to.

Finished

Your Global GitHub App for Terraform Enterprise is fully installed and configured. You can now create Terraform workspaces based on the GitHub repositories your Global GitHub App has access to.


GitHub App Management

Currently Unsupported Features

Warning: Do not modify or remove the default Client Secret, Private Key, or Webhook Secret.

  • GitHub App Client Secret Rotation
  • GitHub App Private Key Rotation
  • GitHub App Webhook Secret Rotation

Required Permissions and Events

Repository permissions

These permissions are set by default. Do not alter these permissions unless specified to do so in a future Terraform Enterprise release.

PermissionAccess
Commit statusesRead and write
ContentsRead-only
MetadataRead-only
Pull requestsRead-only

Required Subscribe Events

These events are set by default. Do not alter these events unless specified to do so in a future Terraform Enterprise release.

EventDescription
CreateBranch or tag created.
Pull RequestPull request assigned, edited, opened, etc.
DeleteBranch or tag deleted
PushGit push to a repository

Transferring GitHub App Ownership

During the setup process for your GitHub App, you can choose a default owner for the application.

If you want to transfer ownership of the GitHub App to another user or organization, follow the transferring GitHub App ownership instructions. No actions need to be taken within Terraform Enterprise.

Removing Global GitHub App from Terraform Enterprise

Warning: Do not delete the GitHub App from GitHub until you have first removed it from Terraform Enterprise.

In order to remove the GitHub App from your Terraform Enterprise instance, you must first remove all installations for the application in GitHub.

Step 1: Remove GitHub App Installations

Warning: Uninstalling the application will remove the connections it has to workspaces, policy sets, and registry modules.

  1. Go to the admin interface and then click VCS Integrations. The VCS Integrations page appears.

  2. If you previously authorized the GitHub App, accessible installations will be shown. Otherwise, you will need to authorize the GitHub App to continue with the removal.

  3. For each installation, click View in GitHub. A new tab will open showing the installation settings page within GitHub.

    Note: You can also find the list of Installed GitHub Apps on the Applications page in GitHub Settings.

  4. Locate the Danger zone section.

  5. Click Uninstall to uninstall the application. Repeat this process for each installation.

Step 2: Remove GitHub App from Terraform Enterprise

After you have removed all GitHub App installations, remove the GitHub App from Terraform Enterprise.

Note: You may need to refresh the VCS Integrations page to verify that all app installations have been removed.

  1. Click the red delete button. A confirmation modal will appear.

  2. In the confirmation modal, click Delete. A success message will appear and you will be navigated back to the admin interface home page.

  3. You are now free to delete the GitHub App in GitHub.

Additional Resources