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.
-
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:
- 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>" } } }
-
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
-
Run the command and the output; if there are no errors, the results should return and display in accordance with this sample response.
-
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.