Configuration-Free GitHub Usage
These instructions are for using repositories from GitHub.com with Terraform Cloud 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.
Note: This VCS Provider is only available on Terraform Cloud. If you are using Terraform Enterprise, you can follow the instructions for creating GitHub App for TFE or connecting to GitHub.com via OAuth.
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).
When using the Terraform Cloud GitHub App, each Terraform Cloud user authenticates individually, and can use GitHub resources within Terraform Cloud according to their own GitHub organization memberships and access permissions.
Note: This is different from OAuth connections, where a Terraform Cloud organization always acts as one particular GitHub user.
To enable this personalized access, Terraform Cloud requests two kinds of permissions:
- Per user: Each Terraform Cloud user must authorize Terraform Cloud for their own GitHub account. This lets Terraform Cloud 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 Terraform Cloud to access repository contents and events.
Individual Terraform Cloud 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 Terraform Cloud users within the same organization can see different sets of repositories available for their workspaces.
Terraform Cloud 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 Terraform Cloud organizations without needing to re-authorize.
Authorization doesn't grant Terraform Cloud any repository permissions; the app must also be installed in at least one of the GitHub organizations or accounts you have access to.
You can use GitHub's web interface to deauthorize Terraform Cloud 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 Terraform Cloud to deauthorize it.
After deauthorizing, you won't be able to connect GitHub repositories to Terraform Cloud workspaces until you authorize again. Existing connections will still work.
Terraform Cloud 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 Terraform Cloud is installed for an organization (or a subset of its repositories), its members can select any affected repositories they have access to when using Terraform Cloud.
Access is not restricted to a specific Terraform Cloud organization; members of a GitHub organization can use its repositories in any Terraform Cloud organization they belong to.
You can use GitHub's web interface to configure or uninstall Terraform Cloud 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 Terraform Cloud to change its settings.
In the app's settings you can change which repositories Terraform Cloud has access to, or uninstall it entirely.
If you disallow access to a repository that is currently connected to any Terraform Cloud workspaces, those workspaces will be unable to retrieve configuration versions until you change their VCS settings and connect them to an allowed repository.
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 Terraform Cloud 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 TFE 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.