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

Use Case

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

Prerequisites

Before updating your workspaces, you must first create a new VCS provider connection in HCP Terraform/Terraform Enterprise that points to the new VCS where the repositories were migrated, if one does not already exist.

You can do this in the UI, through the HCP Terraform/Terraform Enterprise Create an OAuth Client API endpoint, or with the tfe provider's tfe_oauth_client resource.

Procedure

After configuring the new VCS provider, you must modify each workspace's VCS settings with the details of the migrated repository. This requires updating the VCS repository identifier and the OAuth token ID in the workspace settings. You can perform this update using one of the following methods.

Method 1: Using the UI

In the HCP Terraform/Terraform Enterprise application, navigate to each workspace and select Settings -> Version control. Click Change source and select the target repository under the new VCS provider.

Method 2: Using the API

To programmatically perform this update across many workspaces, use the Update a Workspace API endpoint. Each workspace object has a vcs-repo attribute block where you need to update the identifier and oauth-token-id attributes.

• identifier: The new VCS repository identifier in the format <VCS_ORGANIZATION>/<REPO_NAME>.
• oauth-token-id: The OAuth token ID of the new VCS provider. You can find this in the UI at Settings -> Version control -> Providers or by querying the Show an OAuth Client API endpoint.

Execute the following curl command to update a workspace:

$ 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>

The payload.json file should contain the following content:

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

Method 3: Using the tfe Provider

If you already manage your workspaces with Terraform, you can make these updates using the tfe provider's tfe_workspace resource. If the workspaces are not yet managed with Terraform, you can optionally have them imported into Terraform management before updating the VCS settings.

To update the resource, modify the vcs_repo.identifier and vcs_repo.oauth_token_id attributes in your tfe_workspace resource configuration:

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
  }
}

After applying these changes, HCP Terraform/Terraform Enterprise updates the workspace's VCS settings and creates a webhook on the new VCS repository to respond to future VCS events.

Special Considerations for Private Modules

Modules published to the Private Module Registry cannot be patched directly at this time. To update the VCS settings of published modules, you must perform the following steps:

1. List all registry modules and use their source property to identify which modules came from the old VCS connection.
2. Delete each affected module.
3. Create a new module from the repository in the new VCS connection.

Additional Information

• Connecting VCS Providers to HCP Terraform