Configuration-Free GitHub Usage

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.

Authorization doesn't grant HCP Terraform any repository permissions; the app must also be installed in at least one of the GitHub organizations or accounts you have 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.)