Set up the Azure DevOps Services VCS provider

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

This page explains the four main steps required to connect HCP Terraform to your Azure DevOps Services VCS:

1. Create a new connection in HCP Terraform and get the callback URL.
2. On your VCS, register your HCP Terraform organization as a new application. Provide the callback URL and get the application ID and key.
3. Provide HCP Terraform with the application ID and key. Then, request VCS access.
4. On your VCS, approve the access request from HCP Terraform.

Requirements

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

Before you begin, enable Third-party application access via OAuth in Azure DevOps Services settings.

1. Log in to Azure DevOps Services.

2. Click Organization settings.

3. Click Policies under Security.

4. Enable the Third-party application access via OAuth setting.

   

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

1. Go to your organization's settings and then click Providers. The VCS Providers page appears.

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

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

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

Step 2: From your Azure DevOps Services Profile, Create a New Application

1. In a new browser tab, open your Azure DevOps Services Profile, and log in to your Azure DevOps Services account if necessary. A page with a list of your organizations appears.

   Important: The Azure DevOps Services 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 admin 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. If you're unable to load the link above, you can create a new application for the next step at one of the following links: https://aex.dev.azure.com/app/register?mkt=en-US or https://app.vsaex.visualstudio.com/app/register?mkt=en-US.

2. Go into your preferred organization.

3. Click your user icon and then click the ellipses (...) and select User settings.

4. From the User settings menu, click Profile. Your profile page appears.

5. Click Authorizations. The Authorized OAuth Apps page appears.

6. Click the link to register a new app. A form appears asking for your company and application information.

7. Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear and includes controls for copying values to your clipboard. Here is an example:

   Field name	Value
   Company name	HashiCorp
   Application Name	HCP Terraform (<YOUR ORGANIZATION NAME>)
   Application website	https://app.terraform.io (or the URL of your Terraform Enterprise instance)
   Authorization callback URL	https://app.terraform.io/<YOUR CALLBACK URL>

   In the Authorized scopes section, select only Code (read) and Code (status) and then click Create Application.

   

   Important: Do not add any additional scopes beyond Code (read) and Code (status), as this can prevent HCP Terraform from connecting. Note that these authorized scopes cannot be updated after the application is created; to fix incorrect scopes you must delete and re-create the application.

8. After creating the application, the next page displays its details. Leave this page open in a browser tab. In the next step, you will copy and paste the unique App ID and Client Secret from this page.

   If you accidentally close this details page and need to find it later, you can reach it from the Applications and Services links in your profile.

Step 3: On HCP Terraform, Set up Your Provider

1. (Optional) Enter a Name for this VCS connection.

2. Enter your Azure DevOps Services application's App ID and Client Secret. These can be found in the application's details, which should still be open in the browser tab from Step 2.

3. Click Connect and continue. This takes you to a page on Azure DevOps Services, asking whether you want to authorize the app. Click the Accept button and you'll be redirected back to HCP Terraform.

   Note: If you receive a 404 error from Azure DevOps Services, it likely means your callback URL has not been configured correctly.

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.