Terraform Cloud and GitHub together form a common version control and continuous delivery pattern for infrastructure as code. Teams store Terraform configurations in GitHub repositories and let Terraform Cloud detect commits, queue plans, and execute applies. The integration relies on the Terraform Cloud GitHub App for VCS connectivity and on API tokens or CLI-driven runs for automation. The result is auditable infrastructure changes with pull request driven reviews and run history tracked inside Terraform Cloud.
Understanding the Terraform Cloud GitHub App
The Terraform Cloud GitHub App is the mechanism that allows HCP Terraform to read repository contents and react to events. It enables commenting, iteration, and approval of proposed infrastructure changes with a team directly inside GitHub. Integration triggers runs automatically for pull requests. The plan and apply output can be viewed inside Terraform Cloud and the history of all Terraform runs is tracked centrally.
When a user first connects to a version control provider, the flow starts by choosing GitHub.com from the GitHub menu. In organizations with an existing VCS connection, only the connected providers are shown. If management of VCS settings is possible, clicking Connect to a different VCS reveals the provider menus. Otherwise clicking GitHub proceeds with the current provider.
App settings control repository access. Click the Configure button for HCP Terraform to change its settings. In the app's settings it is possible to change which repositories HCP Terraform has access to, or uninstall it entirely. If access to a repository is disallowed that is currently connected to any workspaces or Stacks, those workspaces or Stacks are unable to retrieve configuration versions until VCS settings are changed and they are connected to an allowed repository.
The Terraform Cloud GitHub App can be used to create workspaces and private registry modules from the UI, the API, or the TFE Terraform provider. Minimum versions apply for certain tools. For the UI, Terraform Enterprise v202302-1 or above is required. For the API, Terraform Enterprise v202303-1 or above is required. Using at least v1.19.0 of gotfe, Terraform Enterprise v202303-1 and above is required. Using at least v0.43.0 of tfeprovider, Terraform Enterprise v202303-1 and above is required.
Personalized Access and Authorization Model
The Terraform Cloud GitHub App uses a personalized access model that differs from OAuth connections. Each HCP Terraform user authenticates individually, and can use GitHub resources within HCP Terraform according to their own GitHub organization memberships and access permissions. This is different from OAuth connections, where an HCP Terraform organization always acts as one particular GitHub user.
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 different users within the same organization can see different sets of repositories available for their workspaces or Stacks.
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.
Connecting GitHub as a VCS Provider and Initial Setup
A typical setup starts with preparing a repository and credentials. The tutorial pattern for integrating Terraform Cloud with GitHub to enable the Version Control Workflow involves registering GitHub as a VCS provider so any commit to the repository automatically triggers terraform init, plan, and apply in Terraform Cloud.
Prerequisite is a GitHub account.
Create a GitHub Repository
- Log in to GitHub and click New repository.
- Configure the repository as follows:
Setting | Value
Repository name | clumsy_bird
Description | Your project description
Visibility | Private
Initialize with | README
.gitignore template | Terraform
- Click Create repository.
Generate a GitHub Personal Access Token
You need a Personal Access Token with repo scope to allow Terraform Cloud to read your repository.
- In GitHub, go to Settings > Developer settings > Personal access tokens.
- Click Generate new token, select repo scope, then Generate token.
- Copy the token now — you won’t be able to see it again.
Keep your PAT secure. Do not commit it to any repository or share it publicly.
Once the repository and token exist, the VCS provider instance is created in Terraform Cloud and the GitHub App is installed at the organization or repository level. From that point, workspaces can be created from the UI, API, or provider and linked to a specific branch and folder.
Version Control Workflows with Automatic Runs
Version Control Workflow is the default integration where Terraform Cloud monitors the connected GitHub repository for changes. When a commit lands on the configured branch, Terraform Cloud queues a run. The run performs init, plan, and apply according to the workspace execution mode.
Remote execution mode offloads plan and apply to Terraform Cloud. CLI-driven mode keeps execution local but stores state remotely. The choice affects how GitHub Actions or CI pipelines interact with Terraform Cloud.
A clean integration pattern combines Terraform Cloud remote state, policy enforcement, and secure runs with GitHub Actions triggering those runs for automated infrastructure delivery.
Step 1: Create a Terraform Cloud Workspace
- Create a workspace in Terraform Cloud
- Use a CLI-driven or API-driven workspace if GitHub Actions will run terraform apply
- Configure variables and secrets
Step 2: Create a Terraform Cloud API Token
In Terraform Cloud:
- Create a team token for CI, or a user token with access to the workspace
- Give the token permission to run plans and applies in the workspace
- Store it as a GitHub Actions secret, for example TFC_TOKEN
Step 3: Use the Terraform CLI
The Terraform CLI can trigger CLI-driven remote runs when configuration is connected to Terraform Cloud. Example GitHub Actions workflow:
name: Terraform Cloud
on:
push:
branches: ["main"]
jobs:
apply:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Terraform
uses: hashicorp/setup-terraform@v3
with:
terraform_version: 1.6.6
cli_config_credentials_token: ${{ secrets.TFC_TOKEN }}
- name: Init
run: terraform init
- name: Plan
run: terraform plan -out=tfplan
- name: Apply
run: terraform apply tfplan
If the workspace is configured for remote execution, Terraform Cloud handles the run.
Step 4: Use Run Triggers
Terraform Cloud can trigger downstream workspaces after a successful run. This allows a dependency graph of workspaces to be orchestrated from a single GitHub commit.
Orchestrating GitHub Organization Infrastructure with Terraform
It is not news to store Infrastructure as Code in a GitHub repo to orchestrate Google Cloud Platform, AWS or Azure resources. Managing the GitHub organization itself with Terraform is also supported.
Your GitHub org is infrastructure. Managing it with Terraform brings version control, code review, and repeatable automation to repositories, teams, and permissions. Define sub-teams and access policies declaratively, derive permissions from topics or a simple assignment file, and track every change in git.
Treat your GitHub organization like infrastructure. Put repos, teams, and permissions under version control, review changes with pull requests, and let Terraform apply them safely and repeatably. Start with a small set of repos and teams, lean on locals and for_each to stay DRY, and automate everything in Terraform Cloud so org changes are auditable.
This approach applies the same Version Control Workflow to the GitHub provider configuration. Changes to teams, repository settings, and branch protection are proposed via pull requests, planned in Terraform Cloud, and applied after approval.
Operational Considerations and Limits
Repository visibility and app installation scope directly affect what Terraform Cloud can see. An organization may install the Terraform Cloud app globally or for specific repositories. Users will only see repositories where both personal access and app installation allow access.
Access revocation has immediate effect. If a repository is disallowed in the app settings, connected workspaces lose the ability to retrieve configuration versions until the VCS settings are updated.
Personal access tokens for GitHub should be limited to repo scope and stored securely. Do not commit tokens to repositories. Token rotation should be managed outside of Terraform configurations.
For CI pipelines, prefer team tokens scoped to a workspace rather than long-lived user tokens. Store the token as a GitHub Actions secret and reference it as cliconfigcredentials_token for the setup-terraform action.
When using CLI-driven runs, the workflow runs terraform init, plan, and apply locally, but state and locking are handled by Terraform Cloud. Remote execution mode avoids exposing credentials in CI and centralizes policy checks.
Conclusion
The Terraform Cloud GitHub integration is built around personalized user authorization and organization-level app installation. The Terraform Cloud GitHub App provides the VCS connection that lets workspaces react to pull requests and commits while keeping access decisions aligned with GitHub memberships. Pairing this with API tokens and GitHub Actions creates a repeatable delivery path for infrastructure, and extending the pattern to manage GitHub organizations themselves closes the loop between platform and code.
Effective use requires careful scoping of app installation, disciplined token management, and clear separation between remote execution and CLI-driven workflows. When these pieces are aligned, teams get auditable infrastructure changes, automated plans on every commit, and a single source of truth for both cloud resources and the repositories that define them.