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 nonsupported 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 that 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 instead in which would be obtained from the VCS provider as part of the workflow.   

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. First, we need to create a Personal Access Token from the Github user account and copy it securely where it can be retrieved. (The Personal Access Token creation for the other providers are listed below ) 

   • GitHub and GitHub Enterprise
   • GitLab, GitLab Community Edition, and GitLab Enterprise Edition
   • Azure DevOps Server
2. Next, use the create an oauth client API to set up the connection between an organization and the Github VCS provider using that Personal Access Token created in step 1. I have provided a sample payload.json file template to reference below 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. Then configure the sample request curl command as such similar 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 no errors, 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.  

Additional Information

• For additional assistance please contact HashiCorp Support to request additional assistance.