Set up the Azure DevOps Services VCS provider using personal access tokens

These instructions describe how to use a personal access token to connect HCP Terraform to Azure DevOps Services VCS, which is hosted at dev.azure.com. Connecting to Azure DevOps Services VCS lets you take advantage of HCP Terraform's VCS features.

If you do not intend to use personal access tokens to connect to Azure DevOps Services, refer to Set up the Azure DevOps Server VCS provider. For information about other supported VCS providers, refer to Connect to VCS Providers.

Requirements

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

To connect HCP Terraform to your repositories, your account must have Project Collection Administrator access enabled for all projects containing Terraform configurations. This permission is required to create webhooks because Microsoft doesn't allow you to create custom roles with lower-level access for this purpose.

Personal access token maintenance

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 have a maximum lifetime of one year. When the token expires, HCP Terraform cannot connect to Azure DevOps Services until the token is replaced. To avoid a gap in service, do one of the following actions before the token expires:
  • Update the expiration date of the existing token within Azure DevOps Services.
  • Create a new token and update the VCS configuration in HCP Terraform VCS connection to use it.

Refer to the Azure DevOps documentation for instructions on working with personal access tokens.

Step 1: Add a new VCS provider in HCP Terraform

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: Create a new personal access token in Azure DevOps Services

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. Many organizations use a dedicated service user but a personal account is acceptable.

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 an expiration that meets your requirements.

4. Click Create.

5. Copy the generated token to your clipboard so that you can use it in the next step. Leave this page open in a browser tab.

Step 3: Add the personal access token on HCP Terraform

1. Return to the browser window you opened in Step 1: Add a new VCS provider in HCP Terraform.
2. In the second step under Set up provider, specify a name for your VCS provider a name in the Name field. This field is optional.
3. In the second step under Set up provider, paste the Azure DevOps Services personal access token you copied in step 2 into the Personal Access Token field.
4. Click Connect and continue** to continue.

Step 4: Configure advanced settings in HCP Terraform (optional)

It is optional, but you can configure the following settings in the Advanced Settings screen:

• In the Scope of VCS Provider setting, enable workspaces to use repositories from this VCS provider. All Projects is enabled by default. This setting lets all workspaces in the organization use the VCS provider.
• In the Set up SSH Keypair setting, you can add or update an SSH key and OAuth credentials so that HCP Terraform can access Git submodules in repositories that require them. You configure these settings later.

If you don't need to configure either of the advanced settings, click Skip and Finish to complete the setup and return to HCP Terraform's VCS Provider page, which includes your new Azure DevOps Services client. Otherwise, complete the following steps.

Limit the scope of this VCS provider

1. Enable Selected Projects 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 Update VCS Provider to save your selections.

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

Add an SSH key pair

HCP Terraform only uses SSH to clone Git submodules and uses HTTPS for all other Git operations. Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Services. You should generate a new key 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, HCP Terraform retains the key and uses for authenticating with Azure DevOps Services.

1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to the Azure DevOps Services domain. The following example uses the ssh-keygen command to create a service_terraform file with the private key and a service_terraform.pub file with the public key:

   $ ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise"
   

   Warning

   The passphrase for the SSH key must be empty. HCP Terraform cannot use SSH keys that require a passphrase.

2. Log into the Azure DevOps Services account you want HCP Terraform to act as and navigate to the SSH Keys settings page.

3. Add a new SSH key and paste the value of the SSH public key you just created.

4. 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.

Next steps

Azure DevOps Services access for HCP Terraform is fully configured. You can create Terraform workspaces based on your organization's repositories.