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

These instructions describe how to use repositories on GitHub.com with workspaces or Stacks 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, changing a workspace's VCS connection, or creating or configuring Stacks. 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 have access to several drop-down menus sorted by product family. Choose GitHub.com from the GitHub menu.
• In organizations with an existing VCS connection, only the connected providers are shown. If you can manage VCS settings, click Connect to a different VCS to reveal the provider menus. Otherwise, click GitHub.

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 users within the same organization can see different sets of repositories available for their workspaces or Stacks.

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.

The API and the tfe provider do not trigger the browser-based GitHub authorization pop-up. Any user whose API token connects workspaces, Stacks, or modules to a GitHub App-backed repository must complete that browser-based authorization at least once before their token works for that operation. Refer to GitHub App-backed VCS and API token types for how each token type interacts with this requirement.

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 or Stack 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 or Stack, 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. Sign in to HCP Terraform and navigate to the organization where you want to adjust your VCS settings.
2. Choose Workspaces from the sidebar.
3. Click New, then select Workspace.
4. Choose the project where you want to create your workspace, then click Create.
5. Click Version Control Workflow, then choose the GitHub App.
6. 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 or Stacks 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 workspaces or Stacks, those workspaces or Stacks are 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.)

Troubleshooting

HCP Terraform returns a 422 error with the "doesn't exist or isn't accessible" error message when it cannot confirm that the calling identity has access to the requested repository.

Use the following guidance to resolve common errors when you connect HCP Terraform to a GitHub App-backed repository. The workspace endpoints return the same message for more than one cause, so review every section that lists the message you received. Stack errors begin with the prefix VCS Connection Validation failed:.

The calling user has not linked a GitHub account

• Workspace error message: Repository requires the authenticated user to link a GitHub account via the GitHub App.
• Stack and registry module error message: The authenticated user has not linked a GitHub account to HCP Terraform via the GitHub App. Link your GitHub account in user settings.

The user who owns the API token has not authorized the Terraform Cloud GitHub App on their personal GitHub account. The user must sign in to HCP Terraform and complete the authorization. Refer to Authorizing for more information.

The API token is a team or organization token

• Workspace error message: Repository requires the authenticated user to link a GitHub account via the GitHub App.
• Stack and registry module error message: Team and organization API tokens cannot currently be used to create or update workspaces connected to GitHub App-backed repositories.

Team and organization tokens cannot complete a personal GitHub OAuth flow. Authenticate with a user API token whose owner has authorized the Terraform Cloud GitHub App. Refer to GitHub App-backed VCS and API token types for more information.

The user's linked GitHub account cannot access the repository

• Workspace error message: Repository doesn't exist or isn't accessible.
• Stack and registry module error message: The specified repository "<owner>/<repo>" doesn't exist or isn't accessible to the authenticated user's linked GitHub account.

The user is linked but their personal GitHub account does not have read access to the repository. Grant the user access to the GitHub repository.

The GitHub App installation cannot see the repository

• Workspace error message: Repository doesn't exist or isn't accessible.
• Stack and registry module error message: The specified repository "<owner>/<repo>" doesn't exist or isn't accessible.

This error occurs when the installation's allowed repository list does not include the repository, the repository identifier is wrong, or GitHub has revoked the App's installation token. To resolve the error, adjust the GitHub App installation's repository selection on GitHub or confirm that the :owner/:repo identifier matches the repository on GitHub. Refer to Configuring and Uninstalling for instructions to change the installation's repository selection.