How to Migrate VCS Providers in Terraform Cloud/Enterprise VCS-Driven Workspaces

Use Case

An organization is migrating its repositories to a new VCS provider and needs to update the VCS settings in its VCS-driven workspaces with the new provider and repository details.

Procedure

The first step in this process is to create a new VCS provider in Terraform Cloud/Enterprise which connects to the new VCS to which the repositories were migrated, if it does not already exist. This can be done in the UI, through the Terraform Cloud/Enterprise API, or through the tfe provider.
 
Next, each workspace's VCS settings will need to be modified with details of the migrated VCS repository. This will require updating the VCS repository identifier and oauth token in the workspace settings.

UI

In the Terraform Cloud/Enterprise application, navigate to each workspace and select Settings -> Version control. Click Change source under Version control, and select the target repository under the VCS provider to which it was migrated.

API

To programmatically perform this update across many workspaces, implement this procedure with the Update a workspace API. Each workspace object has a vcs-repo attribute block in which the identifier and oauth-token-id attributes will need to be updated with the VCS repository identifier (<VCS_ORGANIZATION>/<REPO_NAME>) and oauth token of the new VCS provider. The latter of the two can be found at Settings -> Version control -> Providers under the OAuth Token ID attribute of the target VCS provider or through querying the Show an OAuth Client API.

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/<TFC_ORGANIZATION>/workspaces/<WORKSPACE_NAME>

• payload.json:

{
  "data": {
    "attributes": {
      "vcs-repo": {
        "identifier": "<VCS_REPO_IDENTIFIER>",
        "oauth-token-id": "<OAUTH_TOKEN_EXTERNAL_ID>"
      }
    },
    "type": "workspaces"
  }
}

TFE Provider 

If these workspaces are already managed in Terraform, these updates can be made using the tfe provider's tfe_workspace resource. If the workspaces are not yet managed through Terraform, they can optionally be imported and then adjusted with the new VCS settings.

To update the resource, modify the tfe_workspace resources' vcs_repo.identifier and vcs_repo.oauth_token attributes:

resource "tfe_workspace" "test" { 
  name         = "my-workspace-name"
  organization = var.tfc_organization
  
  vcs_repo {
    identifier     = "<VCS_REPO_IDENTIFIER>"
    oauth_token_id = tfe_oauth_client.<NEW_OAUTH_CLIENT>.oauth_token_id
  }
}

Special Considerations for Private Modules

Modules published to the Private Module Registry cannot be patched at this time. To update the VCS settings of published modules, the following steps will need to be taken:

1. List all registry modules and use their source property to determine which ones came from the old VCS connection.
2. Delete each affected module, then create a new module from the new connection's version of the relevant repo.

Conclusion

These changes are sufficient for Terraform Cloud/Enterprise to update the workspace's VCS settings with the details to the new VCS repository as well as initiate the creation of a webhook on the new VCS repository to allow it to respond to future VCS events.

Additional Information

• Connecting VCS Providers to Terraform Cloud