How to create a VCS connection using a Personal Access Token

Introduction

This particular functionality only supports VCS providers GitHub and GitHub Enterprise, GitLab, GitLab Community Edition, GitLab Enterprise Edition, and Azure DevOps Server.  A more comprehensive list of supported VCS providers is found here.

Use Case

When creating a VCS connection to a Terraform Cloud (TFC)/Terraform Enterprise (TFE) Organization or workspace, configuring authentication for the VCS connection usually requires OAuth access and the process takes place within the TFC/TFE GUI Organization or Workspace.  Alternately, you can skip this OAuth configuration process by using the TFC/TFE API to create the client and authenticate with a personal access token obtained from the VCS provider instead.   

Procedure

These steps will be conducted using the GitHub provider as an example. The other providers (listed as supported) would follow the same procedure.  

1. Create a Personal Access Token from the Github user account and copy it securely where it can be retrieved. Personal Access Token creation documentation for GitHub and other providers is listed below:

   • GitHub and GitHub Enterprise
   • GitLab, GitLab Community Edition, and GitLab Enterprise Edition
   • Azure DevOps Server
2. Use the create an oauth client API to set up the connection between an organization and the Github VCS provider using the Personal Access Token created in step 1. I have provided a sample payload.json file template below to reference that contains the 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": "<insert personal access token>"
       }
     }
   }

    

3. Configure the sample request curl command as below to match your TFC/TFE environment and don't forget to supply the $TOKEN

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

4. Run the command and the output; if there are no errors, the results should return and display in accordance with this sample response.

5. Use this API to list the newly created client or view it from within the TFC/TFE GUI comparable with the URL https://<your-tfe-url>/app/<Org name>/settings/version-control to ensure the client creation was accomplished successfully.