Skip to main content
Delivery Metrics

Integrating CodeScene with Azure DevOps

CodeScene integrates with Azure DevOps Boards to retrieve cost and work type trends from your work items. This lets CodeScene allocate costs to hotspots and detect delivery performance patterns, such as planned versus unplanned costs, batch sizes and delivery lead times.

Before you start

Make sure that:

  • Your Azure DevOps work item IDs (for example AB#1234 or #1234) are included in commit messages, branch names or pull requests.

  • You have an Azure DevOps Personal Access Token (PAT) with read access to work items in all relevant projects.

  • You are on a CodeScene Pro subscription. PM integration is a CodeScene Pro feature.

Each CodeScene project uses one PM tool. You can connect one project to Azure DevOps and another to Jira, but not both in the same project.

1. Navigate to PM Data Integration

Go to your Project Configuration in CodeScene. Click on PM Data Integration.

2. Select Azure DevOps

From the list of available PM tools, select Azure DevOps.

3. Enter Azure DevOps API Credentials

  • Organization: Enter your Azure DevOps organization name. For https://dev.azure.com/contoso, enter contoso.

    • If your repositories are hosted in Azure Repos, CodeScene can infer the organization from the repository URL.

    • If your repositories are hosted elsewhere (for example GitHub, GitLab or Bitbucket), you must enter the organization manually.

  • Personal Access Token: enter your Azure DevOps Personal Access Token. See step 4.

4. Create an Azure DevOps Personal Access Token

  1. Sign in to Azure DevOps (https://dev.azure.com/<your-organization>).

  2. Click User settings (the person icon in the top-right corner) → Personal access tokens.

  3. Click + New Token.

  4. Give the token a descriptive name, for example CodeScene PM integration.

  5. Under Organization, select the organization that holds your work items.

  6. Set an Expiration date. Azure DevOps allows a maximum of one year.

  7. Under Scopes, select Custom defined, then enable:

    • Work Items: Read

    • Code: Read (needed to read pull request data)

  8. Click Create and copy the token. You won't be able to see it again.

See Microsoft's guide: Use personal access tokens.

Which permissions does the token need?

The token needs Work Items: Read and Code: Read. The token inherits the access of the user who created it. That user must be able to read work items in every Azure DevOps project your commits refer to, since one CodeScene project can reference work items from more than one Azure DevOps project.

5. Select Cost Unit

Choose Estimated development time (cycle based) for your costs in the integration setup. We recommend this option for all new setups. The other cost units (Issues, Points, Minutes) rely on custom cost fields and will be deprecated.

6. Configure Additional Options

Map Subtasks to Parent Issues

Attributes work on a child work item (for example a Task) to its parent (for example a User Story). The mapping goes up one level. See What Does the 'Map Subtasks to Parent Issues' Option Do?

Map Commits to Pull Request Issues

When enabled, CodeScene asks your Git provider which commits belong to each pull request. Commits are then linked to the work items referenced in the pull request, even if the commit messages don't mention them. This needs the Code: Read scope.

Additional Optional Settings

  • Rename Work Types: changes how work types appear in CodeScene's charts. It does not change anything in Azure DevOps.

  • Project Aliases: generally not required with Azure DevOps. Use it only if your commits reference work items under a different project name.

7. Verify Credentials and Fetch Data

Click Update and Continue. If a second page appears, your credentials are correct.

8. Configure External Projects

Select the Azure DevOps projects you want to integrate with CodeScene from the External Projects list. Include every project your commits refer to.

Then check these fields against your Azure DevOps process:

  • Work In Progress Transition Names: the state that means development has started.

  • Work Done Transition Names: the state that means the work is finished.

  • Defect Work Types: the work item types treated as defects, typically Bug.

The state names depend on your process template:

Process

Work In Progress

Work Done

Agile

Active

Resolved, Closed

Scrum

Committed

Done

Basic

Doing

Done

CMMI

Active

Resolved, Closed

If your organization uses a custom process, use the state names from your own board.

9. Submit and Re-run Analysis

Click Submit to save your configuration. Re-run the analysis.

10. Where to find your Azure DevOps data in CodeScene

After the analysis, Azure DevOps data appears in these places:

  • Delivery: the project's Delivery tab.

    • Unplanned Work is the share of time spent on unplanned tasks, such as bugs, out of the time spent on all tasks. See What is Considered Unplanned Work?

    • Development Time is the average lead time per task, from In Progress to the last commit that references the task.

    • Pending Work shows work that is started but not finished.

  • Hotspots: Defects and Costs on the hotspot map.

A few things to keep in mind:

  • A work item only appears in Delivery if at least one commit is linked to it.

  • Only commits on the main analysis branch are counted.

  • Delivery metrics such as cycle time and lead time need the Work In Progress transition names from step 8.

How CodeScene links commits to Azure DevOps work items

The syntax depends on where your repositories are hosted:

Repositories hosted in

Reference format

Example commit message

Azure Repos

#<ID>

#1234 Fix login timeout

GitHub, GitLab, Bitbucket or other

AB#<ID>

AB#1234 Fix login timeout

  • Azure Repos: #1234 is scoped automatically to the organization and project of the repository.

  • Other Git providers: use Microsoft's AB# (Azure Boards) syntax. The organization then comes from the PM configuration, not the repository URL. See Link GitHub commits to Azure Boards.

  • Pull requests: with Map Commits to Pull Request Issues enabled, commits are linked to work items referenced in the pull request.

When PM integration is enabled, the Ticket ID Pattern is set automatically to match Azure DevOps work item references. If your commits use a different format, see What to Do When the Ticket ID Pattern Does Not Match.

Troubleshooting

Credentials are rejected, or no second configuration page appears

You may also see: "Check your PM data configuration and ensure that the configured API credentials are sufficient for accessing the external projects." Check that:

  • The token has the Work Items: Read and Code: Read scopes.

  • The token was created for the right organization, or for All accessible organizations.

  • The token hasn't expired or been revoked.

  • The Organization field matches your Azure DevOps organization name exactly.

The analysis fails because the organization is missing

This happens when your repositories are not hosted in Azure Repos, so CodeScene can't infer the organization from the repository URL. Enter the Organization manually in the PM integration settings and re-run the analysis.

Some Azure DevOps projects show no data, or are missing from External Projects

This usually means the user behind the token can't access those projects.

  1. Sign in to Azure DevOps as the token's user and check which projects you can see.

  2. Ask an Azure DevOps administrator to grant read access to the missing projects.

  3. Create a new token if needed, update the configuration and run a new analysis.

Commits are not linked to work items

  • If your repositories are on GitHub, GitLab or Bitbucket, commits must use AB#1234, not #1234.

  • Only commits on the main analysis branch are counted. Work on other branches shows up once it's merged.

Delivery shows "Not available", or a Delivery Performance warning

  • Check that the Work In Progress and Work Done transition names exactly match the states on your Azure DevOps board.

  • Check that your commits reference work item IDs in the right format (see above).

  • Allow time for data to build up, especially after moving from another PM tool. Try the weekly view.

Update an expired token

To update an expired token or other credentials, use Update configuration in the PM integration settings. This reloads the PM data used in the analysis.

Timeout errors during PM analysis

Large Azure DevOps organizations can exceed the default 30-second timeout. Set the environment variable PM_DATA_TIMEOUT_MS to a larger value, for example 60000. See How to Handle a Timeout Error During PM Analyses?

Related articles

Was this helpful?

Still need help? Ask the team