Configure the Azure DevOps data source

This document explains how to configure the Azure DevOps data source in Grafana.

Before you begin

Before you configure the data source, ensure you have:

Grafana permissions: Organization administrator role.
Grafana plan: A Grafana Cloud Pro or Advanced plan or an activated on-prem Grafana Enterprise license.
Azure DevOps account: An Azure DevOps organization (cloud) or Azure DevOps Server instance (on-prem).
Personal access token (PAT): A PAT with the required scopes. Refer to Create a personal access token.

Add the data source

To add the Azure DevOps data source:

Click Connections in the left-side menu.
Click Add new connection.
Type Azure DevOps in the search bar.
Select Azure DevOps.
Click Add new data source.

Configure settings

The Azure DevOps data source has required and optional settings.

Required settings

Setting	Description
URL	The URL of your Azure DevOps organization. For Azure DevOps Services, use `https://dev.azure.com/<ORGANIZATION>`. For Azure DevOps Server (on-prem), use the URL of your server instance.
PAT	The personal access token used to authenticate with Azure DevOps. Refer to Create a personal access token. Once saved, the field displays “Configured”. Click Reset to enter a new token.

Optional settings

These settings appear under the Optional Configuration section.

Setting	Description
Projects limit	The maximum number of projects to retrieve. Default: `100`. This value applies to the project picker in the query editor, template variable queries, and the health check. Increase this value if your organization has more than 100 projects.
Username	The username of the PAT owner. This may be needed for some versions of Azure DevOps Server (on-prem).
Secure Socks Proxy	Enable proxying the data source connection through the secure socks proxy to a different network. This toggle is only visible when the `secureSocksDSProxyEnabled` feature toggle is enabled in Grafana 10 or later. Refer to Configure a datasource connection proxy for more information.

Create a personal access token

The Azure DevOps data source authenticates using a personal access token (PAT).

To create a PAT:

In Azure DevOps, click your profile icon in the upper right and select Personal access tokens.
Click New Token.
Provide a name and set the expiration period.
Select the required scopes listed in the following table.
Click Create and copy the generated token.

For detailed instructions, refer to the Azure DevOps PAT documentation.

Required PAT scopes

Set the following scopes to Read access for the features you plan to use:

Scope	Required for
Code (Read)	Repositories and pull request queries
Build (Read)	Build and build definition queries
Release (Read)	Release, release definition, and deployment queries

You can omit scopes for features you don’t use.

Verify the connection

Click Save & test to verify the connection. A successful connection displays one of the following messages:

healthcheck successful. N projects found

or, when the Secure Socks Proxy toggle is enabled:

Successfully connected to Azure DevOps. Found N projects.

In both cases, N is the number of projects accessible with your PAT. If the connection test fails, refer to Troubleshoot Azure DevOps data source issues.

Provision the data source

You can define the data source in YAML files as part of Grafana’s provisioning system. For more information, refer to Provisioning Grafana.

apiVersion: 1

datasources:
  - name: Azure DevOps
    type: grafana-azuredevops-datasource
    access: proxy
    jsonData:
      url: https://dev.azure.com/<ORGANIZATION>
      projectsLimit: 100
      # Optional: set username for Azure DevOps Server (on-prem)
      # username: <USERNAME>
      # Optional: enable secure socks proxy
      # enableSecureSocksProxy: true
    secureJsonData:
      patToken: <PAT_TOKEN>

Key	Description
`jsonData.url`	Required. The Azure DevOps organization or server URL.
`jsonData.projectsLimit`	Optional. Maximum number of projects to retrieve. Default: `100`.
`jsonData.username`	Optional. PAT owner username for Azure DevOps Server.
`jsonData.enableSecureSocksProxy`	Optional. Enable secure socks proxy. Default: `false`.
`secureJsonData.patToken`	Required. The personal access token.

Provision the data source with Terraform

You can provision the Azure DevOps data source using the Grafana Terraform provider. For more information, refer to Provision Grafana with Terraform.

resource "grafana_data_source" "azure_devops" {
  type = "grafana-azuredevops-datasource"
  name = "Azure DevOps"

  json_data_encoded = jsonencode({
    url            = "https://dev.azure.com/<ORGANIZATION>"
    projectsLimit  = 100
    # Optional: set username for Azure DevOps Server (on-prem)
    # username     = "<USERNAME>"
    # Optional: enable secure socks proxy
    # enableSecureSocksProxy = true
  })

  secure_json_data_encoded = jsonencode({
    patToken = "<PAT_TOKEN>"
  })
}