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.
Go to the admin interface and then click VCS Integrations. The VCS Integrations page appears.
Click Create global GitHub App. The Location and GitHub App Owner options appear.
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.
Field Value HTTP URL https://<GITHUB INSTANCE HOSTNAME>API URL https://<GITHUB INSTANCE HOSTNAME>/api/v3For 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.
Click Create global GitHub App. You will be redirected to the Create GitHub App screen on GitHub.
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.
Click Authorize. The GitHub Authorization dialog appears.
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.
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.
| Permission | Access |
|---|---|
| Commit statuses | Read and write |
| Contents | Read-only |
| Metadata | Read-only |
| Pull requests | Read-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.
| Event | Description |
|---|---|
| Create | Branch or tag created. |
| Pull Request | Pull request assigned, edited, opened, etc. |
| Delete | Branch or tag deleted |
| Push | Git 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.
Go to the admin interface and then click VCS Integrations. The VCS Integrations page appears.
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.
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.
Locate the Danger zone section.
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.
Click the red delete button. A confirmation modal will appear.
In the confirmation modal, click Delete. A success message will appear and you will be navigated back to the admin interface home page.
You are now free to delete the GitHub App in GitHub.