GitHub App vs. OAuth for Terraform integration

When using GitHub as the version control system (VCS) provider for Terraform, it’s hard to decide which authentication methods the organization should adopt: GitHub App or GitHub OAuth?

In this blog, we’ll explore the differences between these two methods, their advantages, drawbacks, and best practices. This will help you choose the right approach based on your team’s security and operational requirements. Whether you're managing a small project or an enterprise Terraform setup, understanding these options will help you optimize your workflow and security posture.

»About GitHub App vs. OAuth

If you have already know how GitHub App and GitHub OAuth work in the Terraform integration, you can skip this section.

»About GitHub App

A GitHub App is a type of integration designed to interact with GitHub repositories and organizations independently of any individual user. It uses fine-grained permissions, gives the user more control over which repositories the app can access, can be installed in multiple repositories, and remains active even if a user who installed the app on an organization leaves the organization.

• Set up the GitHub.com (GitHub App) VCS provider for HCP Terraform.

»About GitHub OAuth

GitHub OAuth apps use personal user authentication to access repositories. You can create and register an OAuth app under your personal account or under any organization you have administrative access to. If the user who created the GitHub Oauth app leaves the organization, access may be lost.

• Set up the GitHub.com OAuth VCS provider for HCP Terraform.

»Categories to consider

When an organization uses GitHub as the VCS provider for Terraform to create workspaces, it must choose an authentication method: GitHub App, OAuth, or both. Each method has its own advantages and limitations. Several factors should be considered when making this decision. Key considerations include:

»GitHub repository setup

In this blog, we will focus on repository setup and access control for GitHub repositories.

• Repository structure: Repositories can be structured either by projects or teams:
  • By IT projects: Each project is independent, with minimal cross-team collaboration.
  • By organization teams: Teams often need to share resources across multiple projects they own.
• Repository permissions: Setting the right permissions is essential for Terraform workspaces. Organizations must follow the least-privilege principle when granting access rights.
  • Read access: Required for Terraform to pull the latest configuration from GitHub.
  • Write/admin access: Only required for the admin managing the repositories.

»Organizational authentication and permission standards

Authentication and permission determine how an organization manages connections between GitHub and Terraform, ensuring secure and controlled access.

• Management and maintenance of GitHub connections: Here are common concerns from customers regarding GitHub-Terraform integration…
  • Who can set up the connection? How do you define the roles and permissions for configuring GitHub-Terraform connections?
  • What happens if the person who set the connection leaves the company? What are the options for ensuring continuity?
  • Who or which team can see those connections? How do you control visibility and access to Terraform’s VCS integrations?
• Permissions when creating workspaces:
  • Who can use the connection? How do you define which teams or individuals are allowed to use the GitHub-Terraform connection?
  • How do you restrict access and where can you set the restrictions?

»Webhooks and communication

Different authentication methods handle webhooks and repository updates differently. Understanding their impact on Terraform workspaces is key to maintaining efficiency and scalability.

• How do webhooks affect Terraform workspaces? When there are updates in a GitHub repository, Terraform workspaces may be triggered based on the webhook configuration. The impact depends on:
  • Authentication method: GitHub App vs OAuth.
  • Repository changes: Commits, pull requests, or branch merges can trigger Terraform runs.
  • Workspace configuration: Workspaces linked to specific branches may trigger runs automatically, while others require manual confirmation. And you can also define automatic speculative plans in the Terraform workspace.
• Impact on workload and performance: The organization needs to consider the current and future sizes of Terraform deployments.
  • Size of the Terraform deployment: Small-scale deployment vs large-scale deployment.
  • Terraform concurrency limits: HCP Terraform and Enterprise enforce concurrent run limits based on the chosen plan.
    • Free and Standard plans: Lower concurrency, potential queuing delays.
    • Plus, Premium, and Enterprise plans: Higher concurrency but still requires monitoring to prevent performance issues.
  • Number of GitHub repositories per connection: A single GitHub connection can manage multiple repositories, but excessive repositories on one connection may impact webhook performance.

In the next sections, I will dive deeper into these considerations, compare different methods, and discuss their pros and cons.

»GitHub repository setup

Repository structure and permissions are the first things you will look at as you decide whether to use GitHub App, OAuth, or both.

»Repository structure

There are many factors to consider when designing a GitHub repository structure for an organization. When GitHub is used as the VCS provider for Terraform, one of the key decisions is whether to secure repositories by project or by team. Below is a comparison table outlining the pros, cons, and common use cases for structuring IT projects vs organization teams. The GitHub repository structure can impact your choice between GitHub App and GitHub OAuth.

»Repository permissions

Based on the repository structure, the organization needs to determine how to grant and maintain repository access permissions for its members. More information about the access permissions on GitHub can be found here.

»Deep dive: Authentication and permission

GitHub provides an article on the differences between GitHub Apps and OAuth Apps, comparing several factors. However, when it comes to Terraform VCS connections, there is limited information on how these two approaches differ in practice and where to configure access restrictions. This section will present a visualized comparison to help you better understand these differences and make an informed decision.

»GitHub App authentication

This method uses a preconfigured GitHub App for HCP Terraform.This VCS provider is only available on HCP Terraform. If you are using Terraform Enterprise, you can follow the instructions for creating a GitHub App for Terraform Enterprise or connecting to GitHub.com via OAuth.

»Key data point overview:

• Terraform user account: Created within Terraform.
• Repo access list: Defined per GitHub organization, linked to the corresponding Terraform user account (which matches the GitHub user account).
• GitHub:
  • Organization: Each GitHub organization manages a set of repositories.
  • GitHub personal account

»Authentication set up

• Set up requirements:

  • The HCP Terraform App needs to be installed to each GitHub Organization / Personal account. This can be done through a service account/user account in GitHub for the GitHub Organization.
  • The admin (the service account/user account) who manages the GitHub App configuration needs to add the Terraform user accounts with the repositories that they could access.
  • Each HCP Terraform user authenticates individually, and can use GitHub resources within HCP Terraform according to their own GitHub organization memberships and access permissions.

• Installation:

  • GitHub: Each GitHub organization needs to install the HCP Terraform app.
  • HCP Terraform/Terraform Enterprise:
    • Each Terraform user must install the GitHub App initially, but only once. After installation, the user can leverage the GitHub App across multiple organizations within the HCP Terraform platform or Terraform Enterprise tenant.
    • Each user in HCP Terraform will need to authorize the App once, before being able to see available installations and selecting a repository to connect a workspace.
    • HCP Terraform can only have one GitHub App installed.
      

Terraform user account and the corresponding repo access list

• Access permissions:
  • Each Terraform user account is linked to a GitHub user account.
  • A Terraform user's repository list remains the same across the HCP Terraform platform or Terraform Enterprise tenant. For example, TF_User1 will see the same repository list in Terraform Org1 and Terraform Org2.
  • Repository access is managed at the GitHub organization level, where admins define access per user. In the example diagram above, the access is defined in the table “Terraform user account and the corresponding repo access list”. For example, in GitHub Organization A, TF_User1 may have access to repositories A_Dev1 and A_Test2. When TF_User1 creates a workspace using the GitHub App, they will see Organization A: A_Dev1, A_Test2 in the repository list.
  • The same is applicable to the GitHub personal account.
  • With GitHub App, customers can limit which repositories the app has access to. This control is managed within GitHub (under Personal Account/Organization App settings).
  • There is currently no way to limit access within HCP Terraform, and repositories cannot be added except by administering changes directly in GitHub.
  • Users cannot restrict which repositories are available for specific projects or workspaces, unlike in OAuth.
  • A workaround would be to create the workspace programmatically using the TFE provider, specifying which repository will be used in the VCS section. Alternatively, you can block access at plan or apply time using Sentinel for the VCS source.
  • GitHub App installation remains active even after the user who installed it leaves the GitHub organization. As long as the user has access in GitHub to the installation and authorizes the GitHub App within Terraform Enterprise, workspaces can continue to connect to it.

»GitHub OAuth authentication

This method uses a per-organization OAuth connection.

»Key data point overview:

• Terraform user account: In Terraform, user accounts can be created and managed within Terraform itself. When using the GitHub OAuth authentication model, there are two key roles in this approach:
  • Owner: This role is responsible for establishing the GitHub OAuth connection between Terraform and GitHub using personal credentials. The owner can be either an individual user account or a dedicated service account. This role requires permission to manage VCS settings for the organization.
  • User: This role utilizes the existing GitHub OAuth authentication connections within the Terraform project, without needing to establish a new connection.
• Repo access list: Defined per GitHub organization, linked to the corresponding Terraform user account (which matches the GitHub user account).
• GitHub:
  • Organization: Each GitHub organization manages a set of repositories.

»Authentication set up

• Installation:
  • Below are the steps between GitHub and HCP Terraform to set up the connection:

• Below are the settings on the Terraform side to limit which projects can use which connection to access repositories in the GitHub organization.

• Each Terraform organization can have multiple GitHub OAuth connections. For example, Org1 has two GitHub OAuth connections: A_Dev and A_Test.
  

Terraform user account and the corresponding repo access list

• Owner role:
  • TF_Owner could create VCS connections in both Terraform organizations: Org1 and Org2.
  • TF_Owner has access to the repos in GitHub organization A and GitHub organization B.
• User role:
  • TF_User can access Terraform organizations: Org1 and Org2.
    

GitHub OAuth authentication flow

• Access permission
  • The owner (TF_Owner) needs to have the permission to manage VCS settings for the organization.
  • The Terraform user ( TF_User 1, TF_User 2…) needs to have access to the Terraform organization and projects to create workspaces. For example, TF_User 1 could create workspaces in all projects in Org1, it means:
    • If the user is in project Org1_Dev, then the user would see two GitHub OAuth connections are available to use when creating workspaces:
      • A_Dev to create workspaces from all repositories in Organization A.
      • A_Test to create workspaces from all repositories in Organization A.
    • If the user is in project Org2_Dev, then the user would see two GitHub OAuth connections are available to use when creating workspaces in Organization A and Organization B:
      • A_Prod to create workspaces from all repositories in Organization A.
      • B_Prod to create workspaces from all repositories in Organization B.
  • With GitHub OAuth, providers can have different scopes to define which workspaces can use repositories from the VCS provider.
  • If the user account is removed (e.g. when an employee leaves the company), the rest of the team loses access to the connection.
  • A workaround is to create an OAuth connection from GitHub using an organization account.

»Comparison between GitHub App and GitHub OAuth: Authentication and permissions

»Webhooks and communication

HCP Terraform uses webhooks to monitor new commits and pull requests. This section explains how webhooks function differently in a GitHub App connection versus a GitHub OAuth connection. This will help you understand the communication between GitHub and Terraform, as well as the workload triggered when changes occur in the GitHub repository.

»GitHub App authentication

The chart below illustrates how webhooks work with Terraform and the GitHub App.

• GitHub:
  • The organization admin adds the user (TF_User1) to GitHub Organization A.
  • TF_User1 is granted access to the repositories: A_Dev1, A_Test2, and A_Dev2.
  • The GitHub App has a callback URL, for example: callback_user1_url, to manage webhook communications.
• Terraform:
  • User account: TF_User1
  • The user creates two workspaces from the GitHub App connection:
    • Workspace TF_A_Test2 from GitHub repository A_Test2
    • Workspace TF_A_Dev1 from GitHub repository A_Dev1
    • The yellow tunnel represents the global webhook for the GitHub App.
      • All installation events are transmitted through this bridge.
      • The volume of messages received is controlled by:
        • The repositories the GitHub App has access to.
        • The events the GitHub App is subscribed to.
• GitHub App does not require manual webhook registration; it automatically sends requests for all or selected repositories to a single webhook callback URL. If only 10 out of 1,000 repositories are selected, the GitHub App will not receive webhook events from the other 990 repositories.
• Communication between GitHub and Terraform is based on the number of users × the number of repositories assigned to each user. A single pull request (PR) in Repo1 could trigger communication with multiple HCP Terraform/Terraform Enterprise instances.

»GitHub OAuth authentication

The chart below illustrates how webhooks work with Terraform and GitHub OAuth.

• GitHub OAuth requires the application to register a webhook on each repository to receive webhook events.
  • When connecting a workspace to a repository, Terraform registers a webhook for that repository. For example:
    • In project Org1_Test, the workspace WS1 is created using a GitHub OAuth connection with the repository A_Repo1_dev, which triggers the registration of a webhook on that repository.
    • In project Org1_Prod, the workspace WS2 is created using a GitHub OAuth connection with the repository A_Repo1_dev, which triggers the registration of another webhook on that repository.
  • If a repository is not connected to any workspace, GitHub will not send webhook events for it. For example, the repository A_Repo1_test does not have a webhook registered because it is not connected to any workspace in Terraform.
  • Customers may encounter duplicate webhook registrations if they create multiple OAuth clients. For example, the repository A_Repo1_dev has two webhook registrations.
• Communication between GitHub and Terraform is based on the sum of all workspace connections for each repository. For example:
  • If repository A_Repo1_dev has a PR, it will send webhook events to the two workspaces (WS1 and WS2) but will not send webhook events to WS3.
  • If repository A_Repo2_prod has a PR, it will send webhook events to WS3 only.
  • If another repo, e.g. A_Repo1_test has a PR, it won’t send a webhook event to any workspaces.

»Comparison between GitHub App and GitHub OAuth: Webhook and communication

»Example scenario

There is no right or wrong approach when choosing between GitHub App and OAuth, and both can coexist in certain scenarios.

For example, in this case, the customer has the following requirements:

• Restrict workspace creation to a specific project. For example, in project A, the user can only choose certain repositories, while the same user in project B, can choose a different set of repositories.
• Limit repository selection when creating a workspace via the VCS provider.
• Ensure connection continuity when the person who created the VCS connection leaves the team.

Recommended Solution - GitHub OAuth, with the following considerations:

• Manage repositories through a separate GitHub organization since GitHub OAuth does not allow limiting which repositories are listed.
• Use a system/service account in Terraform (or an account that won’t expire) when creating the connections to ensure long-term stability.
• Reduce duplicate webhooks by standardizing OAuth clients within the organization

»Helpful links

• Connect to VCS Providers
• Integration with GitHub App: Describes how to integrate your Terraform Enterprise deployment with a GitHub App.
• Differences between GitHub Apps and OAuth apps