Azure DevOps
Azure DevOps is a Microsoft-owned version control system used for managing the software development lifecycle.
Integrating Cortex with Azure DevOps allows you to:
Automatically discover and track ownership of Azure DevOps entities
Follow a GitOps workflow with Azure DevOps
View information about your Azure DevOps repositories on an entity's details page, including: The repo associated with the entity, recent commits and releases in the event timeline, the most-used language in the files for that entity, the top code contributors, and their number of contributions
If you pull in Azure DevOps pipeline data, you can also see pipeline runs and builds in the CI/CD section of an entity's details page.
If you enable the option to pull in Azure DevOps work items, you will also see a list of open work items on entity pages.
View information about pull requests and work items in the engineering homepage
Use Azure DevOps metrics in Eng Intelligence to understand key metrics and gain insight into services, incident response, and more
Create Scorecards that track progress and drive alignment on projects involving your repositories, Azure DevOps work items, and Azure DevOps pipeline data
How to configure Azure DevOps with Cortex
Prerequisites
Before you get started:
Add a Azure DevOps personal access token with at least the following scopes enabled:
Analytics:
read
Build:
read
Code:
read
If using the Scaffolder with Azure DevOps, you must also enable:
Code:
write
Code:
manage
Graph & Identity:
read
Work Items:
read
andwrite
Configure the integration in Cortex
In Cortex, navigate to the Azure DevOps settings page:
In Cortex, click your avatar in the lower left corner, then click Settings.
Under "Integrations", click Azure DevOps.
Click Add configuration.
Configure the Azure DevOps integration form:
Organization: Enter the slug for your Azure DevOps organization.
Username: Enter the username for your personal access token.
Personal access token: Enter your Azure DevOps personal access token.
Host: Optionally, if you are using a self-managed setup, enter your hostname.
Click Save.
Cortex supports mapping multiple identities for a single user if you have multiple configurations of Azure DevOps. See the Identity mapping documentation for more information.
Enable or disable Azure DevOps work items
On the Azure DevOps settings page in Cortex, you can choose whether Azure DevOps work items should be pulled in from Azure DevOps. Cortex recommends disabling this option if your organization does not use work items or if you are worried about running into rate limit issues.
How to connect Cortex entities to Azure DevOps
Import entities from Azure DevOps
See the Create services documentation for instructions on importing entities.
Editing the entity descriptor
In an entity's YAML, you can define a repository, work items, ownership, and pipelines.
Define a repository
To define an Azure DevOps repository for a given entity, add the x-cortex-git
block to the entity's descriptor.
x-cortex-git:
azure:
project: cortex
repository: docs
basepath: myService
alias: accountAlias
project
The name of the project as listed under the "Projects" tab when you are logged into Azure DevOps (on the https://dev.azure.com// screen)
✓
repository
The repo name you see when you navigate to the "Repos" section of Azure DevOps
✓
basepath
If the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdir
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Only one repository can be defined for in a given entity's YAML in the x-cortex-git
block.
Define work items
Before adding work items to your entity YAML, make sure you have enabled the option to pull in Azure DevOps work items in your integration settings.
To define Azure DevOps work items for a given entity, add the x-cortex-azure-devops
block to the entity's descriptor. If there is no work item registrations, but the entity matches a repository, we will pull in all work items from the repository's project with a tag that matches the Cortex entity name, Cortex entity tag, or the repository name.
x-cortex-azure-devops:
workItems:
projects:
- name: projectName1
wiqls:
- "[System.TeamProject] = 'Design Agile'"
- "[System.WorkItemType] = 'User Story'"
- "[System.State] = 'Active'"
- ORDER BY [System.ChangedDate] DESC ASOF '02-11-2020'
- name: projectName2
alias: alias1
- name: projectName3
alias: alias2
projects
List of the projects
✓
name
The project name as listed under the "Projects" tab when you are logged into Azure DevOps (on the https://dev.azure.com// screen)
✓
wiqls
List of WIQL conditions to filter work items fetched
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Define ownership
Ownership of each entity through Azure DevOps is defined through an owner of type group
.
x-cortex-owners:
- type: group
name: My Azure DevOps Team
provider: AZURE_DEVOPS
description: This is a description for this owner # optional
name
is a case-sensitive field that corresponds to the upstream identifier of your owner from Azure DevOps.
Learn more about ownership in Defining ownership.
Define pipelines
You can add Azure DevOps pipelines under the x-cortex-azure-devops
block:
x-cortex-azure-devops:
pipelines:
projects:
- name: projectName1
pipelines:
- id: 1
- name: projectName2
pipelines:
- id: 2
piepelines
List of the pipelines
✓
projects
List of the projects
✓
name
The project name as listed under the "Projects" tab when you are logged into Azure DevOps (on the https://dev.azure.com// screen)
✓
pipelines:id
The Azure DevOps system.definitionID
for the pipeline.
✓
Learn more about Azure DevOps pipelines in Microsoft's documentation.
Identity mappings for Azure DevOps
Cortex maps users' email addresses to discovered Azure DevOps accounts.
You can confirm users' Azure DevOps accounts are connected from Azure DevOps identity mappings in settings.
Create a work item from an Initiative issue
Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.
From the Issues tab of an Initiative, you can automatically create a Azure DevOps work item from a failing rule:
Click Create issue.
In the modal that appears, fill out the form:
Integration: If you have multiple task tracking tools, select Azure DevOps from the Integration dropdown.
Name: Enter a name for the configuration.
Project: Select from the dropdown.
Options available in the dropdown are pulled in from the specific Azure DevOps instances configured in Settings.
Select the Work item type and the Sub-item Type from the respective dropdowns. Then, select how the sub-items's fields should be populated on issue creation and status change.
Choose to include or exclude groups of entities, or define a more advanced filter.
The issue configuration will apply to all entities that meet the filter criteria. Once an entity is passing the rule, Cortex will automatically close the associated ticket.
Using the Azure DevOps integration
View Azure DevOps data on entity pages in Cortex
The Azure DevOps integration will populate the Repo detail block on an entity's details page.
In the Recent activity preview, you'll find the recent commits and releases. These will also appear in the event timeline.
These data will appear for entities imported from a Git source or those that have a Git repo defined in their YAMLs.
Events
On an entity's Events page, you can find all of the commits and releases associated with that entity. Each is hyperlinked to the commit or release page in Azure DevOps and includes a timestamp.
CI/CD
From the CI/CD > Azure DevOps page in the entity's sidebar, see a history of pipeline runs.
Repository
You can access more detailed information pulled from Azure DevOps under Repository in the sidebar. At the top of the repository page, you'll find the repo associated with that entity and the most-used language in files for that entity. In the Top contributors block, you'll find the three users who have contributed the most code and the number of their contributions.
In the Commits section, you'll find the 10 most recent commits and metadata about each. Below Commits is the Recent releases section, which includes the 5 most recent releases.
Issue tracking
In the Issue tracking section, you can find a list of open Azure DevOps work items. Each work item will show the title, summary, assignees, priority, and date created.
Packages
Packages are automatically scraped from your Git repos or they can be submitted via the packages API. The package file must be in the root of your repository — or, if you're using basepath
, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in CQL explorer using packages()
.
To view packages, click Packages in the entity's sidebar.
The following package types are automatically scraped from repositories:
JavaScript / Node.js:
package.json
,package-lock.json
,yarn.lock
,pnpm-lock.yaml
Python:
requirements.txt
,pipfile.lock
.NET (C#):
packages.lock.json
Java:
pom.xml
Go:
go.sum
All other files of these types can be added via the packages API.
Engineering homepage
The Azure DevOps integration enables Cortex to pull information about pull requests and work items into the homepage. You can find your open pull requests, any pull requests assigned to you for review, and any work items assigned to you.
Pull requests and work items from Azure DevOps are refreshed every 5 minutes.
Eng Intelligence
The Eng Intelligence tool also uses pull request data from Azure DevOps to generate metrics:
Average PR open to close time
Avg time to first review
Avg time to approval
PRs opened
Weekly PRs merged
Avg PRs reviewed/week
Avg commits per PR
Read more about how Eng Intelligence tracks metrics for teams and users in the Eng Intelligence documentation.
Scorecards and CQL
With the Azure DevOps integration, you can create Scorecard rules and write CQL queries based on Azure DevOps work items.
See more examples in the CQL Explorer in Cortex.
Background sync
Cortex conducts a background sync of Azure DevOps identities every day at 10 a.m. UTC. Pull requests and work items are refreshed every 5 minutes.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Chat: Available in the Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a
:ticket:
reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Last updated
Was this helpful?