Set up the Azure DevOps Services VCS provider using Personal Access Tokens

These instructions are for using dev.azure.com for HCP Terraform's VCS features. Other supported VCS providers have separate instructions.

Requirements

Configuring a new VCS provider requires permission to manage VCS settings for the organization.

Important Notes About Authentication

HCP Terraform uses personal access tokens to connect to Azure DevOps Services. This access method requires some additional configuration and ongoing maintenance:

• Personal access tokens eventually expire, with a maximum allowed lifetime of one year. If HCP Terraform's token expires, it will be unable to connect to Azure DevOps Services until the token is replaced. To avoid a gap in service, do one of the following before the token expires:
  • Update the expiration date of the existing token within Azure DevOps Services.
  • Create a new token, and edit HCP Terraform's VCS connection to use it.

Step 1: On HCP Terraform, Begin Adding a New VCS Provider

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization where you want to add the VCS provider.

2. Choose Settings from the sidebar, then click Providers.

3. Click Add VCS Provider. The VCS Providers page appears.

4. Select Azure DevOps and then select Azure DevOps Services from the menu. The page moves to the next step.

5. Select Configure with Personal Access Token

Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform.

Step 2: On Azure DevOps Services, Create a New Personal Access Token

1. In a new browser tab, open your Azure DevOps Services instance and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work.

   Important: The account you use for connecting HCP Terraform must have Project Collection Administrator access to any projects containing repositories of Terraform configurations, since creating webhooks requires these permissions. It is not possible to create custom access roles with lower levels of privilege, as Microsoft does not currently allow delegation of this capability.

2. Navigate to User settings -> Security -> Personal access tokens.

3. Click the New Token button to generate a new personal access token with "Code (Read)" and "Code (Status)" scopes. (We recommend also granting access to "All accessible organizations" and setting the Expiration to a date that works best for you). Click Create.

4. Copy the generated token to your clipboard; you'll paste it in the next step. Leave this page open in a browser tab.

Step 3: Add the Personal Access Token on HCP Terraform

1. On the "Set up provider" step there are two textboxes. Give your VCS provider a name (optional) and enter your Azure DevOps Services Personal Access Token from Step 2. Click the "Connect and continue" button to continue to the next step.

Step 4: On HCP Terraform, Configure Advanced Settings (Optional)

The settings in this section are optional. The Advanced Settings you can configure are:

• Scope of VCS Provider - You can configure which workspaces can use repositories from this VCS provider. By default the All Projects option is selected, meaning this VCS provider is available to be used by all workspaces in the organization.
• Set up SSH Keypair - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time.

If You Don't Need to Configure Advanced Settings:

1. Click the Skip and Finish button. This returns you to HCP Terraform's VCS Provider page, which now includes your new Azure DevOps Services client.

If You Need to Limit the Scope of this VCS Provider:

1. Select the Selected Projects option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider.

2. Click the Update VCS Provider button to save your selections.

If You Do Need an SSH Keypair:

Important Notes

• SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS.
• Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Services; generate a new one or use an existing key reserved for service access.
• In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to Azure DevOps Services.
• Protect this private key carefully. It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them.

1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Azure DevOps Services.com. The exact command depends on your OS, but is usually something like: ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise" This creates a service_terraform file with the private key, and a service_terraform.pub file with the public key. This SSH key must have an empty passphrase. HCP Terraform cannot use SSH keys that require a passphrase.

2. While logged into the Azure DevOps Services account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created.

3. In HCP Terraform's Add VCS Provider page, paste the text of the SSH private key you just created, and click the Add SSH Key button.

Finished

At this point, Azure DevOps Services access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's repositories.