How to replace the VCS connection on workspaces using a script

Avatar
Patrick Munne
  • Updated

Introduction

When you revoke the connection of your VCS provider, all workspaces using this VCS provider will have the VCS provider removed from their settings. You have to manually add the VCS provider on each workspace.

This article provides a script that will enable you to automate the process of updating the workspaces with a new VCS provider. 

 

Prerequisites 

  •  You will need to have the third-party tool jq installed on your system. Download can be found here.
  • TFE token with admin privileges on your Terraform Enterprise (TFE)/ HCP Terraform environment. 

Use Case

You will update 2 workspaces to use a different VCS provider by using the script by following 3 steps:

  1. Gather all the workspaces using the TFE's API and output these to a JSON file
  2. Edit the JSON file to only contain the workspaces on which you want the VCS connection
  3. Run the script that will use the JSON file and update the workspaces with the VCS connection

 

Step 1: Create a JSON file with workspaces to be updated

  • Execute the following to get all your workspaces
export TOKEN=<Organization level token or ADMIN user token>
export ORG_NAME=<Organization name within TFE/TFC>
export HOSTNAME=<The name of your TFE/TFC environment. Example app.terraform.io or patrick.hashicorp.com>

curl --header "Authorization: Bearer $TOKEN" \
 --header "Content-Type: application/vnd.api+json" \
 "https://$HOSTNAME/api/v2/organizations/$ORG_NAME/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=100" | jq -r '[.data[].attributes | {workspace: .name, repo: ."vcs-repo"."display-identifier"}]' > output.json
  • The maximum per-page is 100, so you’ll need to do this multiple times if you have more than 100 workspaces.

Step 2: Edit the JSON file

  • Edit the output.json to only contain the workspaces for which you want to specify the new VCS provider
[
 {
  "workspace": "random_pet_example2",
  "repo": "munnep/random_pet"
 },
 {
  "workspace": "random_pet_example1",
  "repo": "munnep/random_pet"
 }
]
  • Screenshot of the random_pet_example1 workspace settings.
  • Provider: Github.commceclip0.png

Step 3: Execute the script

  • Store the following script as vcs-update-script.sh on your machine. 
#!/bin/bash

# Pass the input file to the script or exit

INPUT_FILE=$1

if [[ -z $INPUT_FILE ]]; then
  echo "Usage: $0 file-to-read"
  exit 1
fi

# Make sure all of the required variables are set.
# This could be more graceful, but should do the trick

if [ -z $TOKEN ] || [ -z $HOSTNAME ] || [ -z $ORG_NAME ] || [ -z $OAUTH_TOKEN ]; then
  printf"Please make sure the following environment variables are set:\n\n"
  printf"%-13s %s\n" \
    "TOKEN""A user token with the appropriate permissions to alter a workspace's VCS settings" \
    "HOSTNAME""The hostname of your Terraform Enterprise instance" \
    "ORG""The organization that the workspaces exists in" \
    "OAUTH_TOKEN""The OAuth token of the VCS connection. Can be found in the organization's VCS settings"
  exit 1
fi

# Break the input file into individual flat objects

WORKSPACES=$(jq -c '.[]' $INPUT_FILE)

# Iterate over the lines, making the appropriate API call

for x in $WORKSPACES; do
  NAME=$(echo $x| jq -r '.workspace')
  REPO=$(echo $x| jq -r '.repo')
 
  printf "Setting VCS connection for %s to %s \n" $NAME $REPO

  # Capture and parse the response, looking for the VCS repo identifier.
  # This allows us to compare the expected result to the *actual* result.

  RESPONSE=$(curl -s \
    --header "Authorization: Bearer $TOKEN" \
    --header "Content-Type: application/vnd.api+json" \
    --request PATCH \
    --data "{\"data\":{\"attributes\":{\"vcs-repo\":{\"identifier\":\"$REPO\",\"oauth-token-id\":\"$OAUTH_TOKEN\"}},\"type\":\"workspaces\"}}" \
    "https://$HOSTNAME/api/v2/organizations/$ORG_NAME/workspaces/$NAME")

  PARSED_RESPONSE=$(echo $RESPONSE| jq -r '.data.attributes."vcs-repo".identifier')

# Report back whether expectation == reality

  if [[ $PARSED_RESPONSE == $REPO ]];then
    printf "Success! \n \n"
  else
    printf "Something went wrong: $RESPONSE \n \n"
  fi

done
  • The script goes over the workspaces defined in the output.json to update the VCS-repo with an API call. The payload we use for this is the following. 
{
 "data": {
  "attributes": {
   "vcs-repo": {
    "identifier": "organization/repository",
    "oauth-token-id": "value-from-VCS-connection"
   }
  },
  "type": "workspaces"
 }
}

 

  • Use the script as follows
export TOKEN=<Organization level token or ADMIN user token>
export ORG_NAME=<Organization name within TFE/TFC>
export HOSTNAME=<The name of your TFE/TFC environment. Example app.terraform.io or patrick.hashicorp.com>
export OAUTH_TOKEN=<This can be found under the VCS provider you configured and want to use>

./vcs-update-script.sh output.json

 

  • Output of the script usage
Setting VCS connection for random_pet_example2 to munnep/random_pet 
Success!

Setting VCS connection for random_pet_example1 to munnep/random_pet 
Success!

 

  • Screenshot of the random_pet_example1 workspace settings.
  • Provider: my-github-oauth-client

mceclip1.png

 

This still involves manually editing the output.json file to have the correct repository settings, but it will save you time instead of having to do this manually. 

Please check this on a development environment to get some experience using the script before attempting in a production environment.

 

Additional Information

Articles in this section

See more

Related articles