VCS connection using Github App fails for SSO enabled Github organisations

Introduction

Problem

When attempting to create a new VCS-driven workspace in HCP Terraform using the GitHub App integration, it doesn't show any repositories in the drop down at first and then when you try to add a new Github org, the process appears to hang which then fails without displaying any error messages in either HCP Terraform or GitHub. However, browser network logs reveal a request failing with HTTP status code 304.

A 304 Not Modified status typically indicates that the resource hasn’t changed since the last request, which should not inherently cause a failure. In this context, it may suggest issues with caching, authorization, or an incomplete handshake between HCP Terraform and the GitHub App—especially in organizations with Single Sign-On (SSO) enabled.

Other observations : 

Although the Terraform Cloud GitHub App appears as installed under the Installed GitHub Apps section on the GitHub side, the JSON response from the API endpoint https://app.terraform.io/api/v2/github-app/installations does not include an installation ID for the affected GitHub organization.

Cause

• Backend logs show HTTP 403 Forbidden responses from GitHub, with an error indicating SAML enforcement is enabled for the GitHub organization.

Error :

Resource protected by organization SAML enforcement. You must grant your OAuth token access to this organization.

Solutions:

• According to GitHub documentation, users must have an active SAML session before authorizing a GitHub App when SSO enforcement is enabled for their organization.
  • Recommended Action:
    To resolve issues related to SAML enforcement and GitHub App authorization:
  • Revoke the existing user-to-server token

    • In GitHub, navigate to:

      • Personal Settings > Applications > Authorized GitHub Apps, or

      • Go directly to: https://github.com/settings/apps/authorizations

      Locate the Terraform Cloud app and revoke its access. 

  • Reauthorize the Terraform Cloud GitHub App
    Revisit HCP Terraform and attempt to connect a workspace to the affected GitHub organization.
    You should be prompted to reauthorize the GitHub App—this time with an active SAML session, which should resolve the access issue.

  • Verify repository access
    After reauthorization, confirm that you're able to view and select repositories under the organization when configuring the workspace.

Note:
Revoking the Terraform Cloud GitHub App authorization will not impact existing workspaces that are already connected to the GitHub App installation.

The user-to-server OAuth token involved here is only used during the workspace setup process. Once the workspace is connected, it continues to receive and process GitHub web hooks. Therefore, revoking and reauthorizing the app will not disrupt the functionality of existing workspaces.

Additional Information

• https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app 

• If you are still not able to solve your issue, please reach out HCP Terraform support at

  tf-cloud@hashicorp.support or submit a ticket via our support portal.