How to create a VCS connection using a Personal Access Token

Introduction

This guide explains how to create a Version Control System (VCS) connection using a Personal Access Token (PAT) via the API. This method provides an alternative to the standard OAuth configuration process in the UI.

This functionality supports the following VCS providers:

• GitHub and GitHub Enterprise
• GitLab, GitLab Community Edition, and GitLab Enterprise Edition
• Azure DevOps Server

Use Case

When creating a VCS connection for an HCP Terraform or Terraform Enterprise organization, the standard process uses OAuth access configured through the UI. As an alternative, you can use the API to create the OAuth client and authenticate with a PAT from your VCS provider, bypassing the UI-based OAuth flow.

Prerequisites

• An API token for your HCP Terraform or Terraform Enterprise organization with appropriate permissions.
• The name of the organization where you will create the VCS connection.

Procedure

These steps use GitHub as an example, but the procedure is the same for other supported providers.

1. Generate a Personal Access Token (PAT)

Create a Personal Access Token from your VCS provider user account and store it securely. Refer to the official documentation for your provider for detailed instructions:

• GitHub and GitHub Enterprise
• GitLab, GitLab Community Edition, and GitLab Enterprise Edition
• Azure DevOps Server

2. Prepare the API Payload

Use the following payload.json file as a template. It contains the required placeholder for the Personal Access Token.

{
  "data": {
    "type": "oauth-clients",
    "attributes": {
      "service-provider": "github",
      "http-url": "https://github.com",
      "api-url": "https://api.github.com",
      "oauth-token-string": "<YOUR_PERSONAL_ACCESS_TOKEN>"
    }
  }
}

3. Create the OAuth Client via API

Use the Create an OAuth Client API endpoint to establish the connection. Configure the curl command below to match your environment, ensuring you provide your API token and organization name.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://<YOUR_TFE_URL>/api/v2/organizations/<YOUR_ORGANIZATION_NAME>/oauth-clients

A successful request will return a sample response containing the details of the newly created OAuth client.

4. Verify the Connection

After running the command, you can verify the client was created successfully in two ways:

1. API: Use the List OAuth Clients API endpoint to confirm the new client appears in the list.
2. UI: Navigate to your organization's VCS provider settings to see the new connection. The URL is typically https://<YOUR_TFE_URL>/app/<YOUR_ORGANIZATION_NAME>/settings/version-control.

Additional Information

• For a comprehensive list of options, refer to the supported VCS providers documentation.