Set up the GitHub.com (GitHub App) VCS provider

These instructions are for using repositories from GitHub.com with HCP Terraform workspaces and private registry modules, without requiring an organization owner to configure an OAuth connection.

This method uses a preconfigured GitHub App, and only works with GitHub.com. There are separate instructions for connecting to GitHub.com via OAuth, connecting to GitHub Enterprise, and connecting to other supported VCS providers.

Using GitHub Repositories

Choose "GitHub.com" on the "Connect to a version control provider" screen, which is shown when creating a new workspace or changing a workspace's VCS connection. Authorize access to GitHub if necessary. On the next screen, select a GitHub account or organization from the drop-down menu (or add a new organization) and choose a repository from the list.

The controls on the "Connect to a version control provider" screen can vary, depending on your permissions and your organization's settings:

• In organizations with no VCS connections configured:
  • Users with permission to manage VCS settings (more about permissions) will see several drop-down menus, sorted by product family. Choose "GitHub.com" (not "GitHub.com (Custom)") from the GitHub menu.
  • Other users will see a "GitHub" button.
• In organizations with an existing VCS connection, only the connected providers are shown. Click the "Connect to a different VCS" link to reveal the provider menus (if you can manage VCS settings) or the GitHub button (others).

GitHub Permissions

When using the Terraform Cloud GitHub App, each HCP Terraform user authenticates individually, and can use GitHub resources within HCP Terraform according to their own GitHub organization memberships and access permissions.

To enable this personalized access, HCP Terraform requests two kinds of permissions:

• Per user: Each HCP Terraform user must authorize HCP Terraform for their own GitHub account. This lets HCP Terraform determine which organizations and repositories they have access to.
• Per GitHub organization: Each GitHub organization (or personal account) must install the Terraform Cloud app, either globally or for specific repositories. This allows HCP Terraform to access repository contents and events.

Individual HCP Terraform users can access GitHub repositories where both of the following are true:

• The user has at least read access to that repository on GitHub.
• The repository's owner has installed the Terraform Cloud app and allowed it to access that repository.

This means that different HCP Terraform users within the same organization can see different sets of repositories available for their workspaces.

Authorizing

HCP Terraform requests GitHub authorization from each user, displaying a pop-up window the first time they choose GitHub on the "Connect to a version control provider" screen.

Once you authorize the app, you can use GitHub in any of your HCP Terraform organizations without needing to re-authorize.

After installing the GitHub App and creating your VCS provider instance, you cannot reinstall the application again. However, you can modify your existing GitHub App configuration.

If you are a repository owner, you can adjust an existing Github App configuration by:

1. Click a repository's Settings tab.
2. Select GitHub Apps in the sidebar.
3. Next to Terraform Cloud, click Configure.
4. Underneath Repository access, adjust the repositories your GitHub app can access.

Now that your Github app has access to your desired repository, you can create a new workspace with your existing, newly updated GitHub App connection.

You can also adjust your GitHub App's access within HCP Terraform itself. Whenever you create a new workspace, you can choose which organizations or repositories to install the GitHub App into. To adjust your GitHub App's configuration, create a new workspace:

1. Click Workspaces in the sidebar.
2. Click New, then select Workspace.
3. Choose the project where you want to create your workspace, then click Create.
4. Click Version Control Workflow, then choose the GitHub App.
5. Click on your GitHub organization's name to reveal a dropdown, then select Add another organization to configure the resources your GitHub app has access to.

Deauthorizing

You can use GitHub's web interface to deauthorize HCP Terraform for your GitHub account.

Open your GitHub personal settings, then go to the "Applications" section and the "Authorized GitHub Apps" tab. (Or, browse directly to https://github.com/settings/apps/authorizations.) Click the Revoke button for HCP Terraform to deauthorize it.

After deauthorizing, you won't be able to connect GitHub repositories to HCP Terraform workspaces until you authorize again. Existing connections will still work.

Installing

HCP Terraform requests installation when a user chooses "Add another organization" from the repository list's organization menu.

The installation interface is a pop-up GitHub window, which lists your personal account and the organizations you can access. Note that installing an app for a GitHub organization requires appropriate organization permissions; see GitHub's permissions documentation for details.

For a given organization or account, the app can be installed globally or only for specific repositories.

Once the application is installed for an organization (or a subset of its repositories), its members can select any affected repositories they have access to when using HCP Terraform.

Access is not restricted to a specific HCP Terraform organization; members of a GitHub organization can use its repositories in any HCP Terraform organization they belong to.

Configuring and Uninstalling

You can use GitHub's web interface to configure or uninstall HCP Terraform for an organization or account.

Open your GitHub personal settings or organization settings, then go to the Applications section and the *Installed GitHub Apps tab. Click the Configure** button for HCP Terraform to change its settings.

In the app's settings you can change which repositories HCP Terraform has access to, or uninstall it entirely.

If you disallow access to a repository that is currently connected to any HCP Terraform workspaces, those workspaces will be unable to retrieve configuration versions until you change their VCS settings and connect them to an allowed repository.

Feature Limitations

You can use the Terraform Cloud GitHub App to create workspaces and private registry modules from the UI, the API, or the TFE Terraform provider. The following tools can use any version of HCP Terraform to access these features, but require a minimum version of Terraform Enterprise:

• For the UI, use Terraform Enterprise v202302-1 or above.
• For the API, use Terraform Enterprise v202303-1 or above.
• Using at least v1.19.0 of go_tfe, use Terraform Enterprise v202303-1 and above.
• Using at least v0.43.0 of tfe_provider, use Terraform Enterprise v202303-1 and above.

Once you decide to start using these other features, a user with permission to manage VCS settings can configure GitHub OAuth access for your organization. (More about permissions.)