Skip to main content

Azure DevOps

CatalogInitiativesScorecards

Overview​

Azure DevOps is a Microsoft-owned version control system used for managing the software development lifecycle.

Integrate one or more Azure DevOps accounts with Cortex to drive insights into values such as:

  • Repository details & work items in the Catalog
  • Scorecard rules
  • Tracking Initiative progress

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:
    • Code: read
      • If using the Scaffolder with Azure DevOps, you must also enable write, and manage.
    • Work Items: read and write
    • Graph & Identity: read

Configure the integration in Cortex​

  1. In Cortex, navigate to the Azure DevOps settings page:
    1. In Cortex, click your avatar in the lower left corner, then click Settings.
    2. Under "Integrations", click Azure DevOps.
  2. 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.
  3. Click Save.

Configure the integration for multiple Azure DevOps accounts​

The Azure DevOps integration has multi-account support. You can add a configuration for each additional by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Azure DevOps page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.

Once you save your configuration, you'll see the last four characters of the token you entered. If you’ve set everything up correctly, you’ll see the option to Remove Integration in Settings.

You can also use the Test all configurations button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

Disable Azure DevOps work items​

Optionally, on the Azure DevOps settings page in Cortex, you can disable Azure DevOps work items from being pulled in from Azure DevOps. This is helpful if your organization does not use work items or if you are worried about running into rate limit issues.

caution

If you do not see the settings page you're looking for, you likely don't have the proper permissions and need to contact your admin.

caution

If you're using a self-hosted instance of Azure DevOps, you'll need to verify that your Cortex instance is able to reach the Azure DevOps instance.

We route our requests through a static IP address. Reach out to support at help@cortex.io to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Azure DevOps instance.

How to connect Cortex entities to Azure DevOps​

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
FieldDescriptionRequired
projectThe name of the project as listed under the "Projects" tab when you are logged into Azure DevOps (on the https://dev.azure.com/{your-organization}/ screen)✓
repositoryThe repo name you see when you navigate to the "Repos" section of Azure DevOps✓
basepathIf the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdir
aliasAlias 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​

To define Azure DevOps work items for a given entity, add the x-cortex-azure-devops block to the entity's descriptor.

x-cortex-azure-devops:
    workItems:
        projects:
            - name: projectName1
              wiqls:
                - wiql1.1
                - wiql1.2
            - name: projectName2
              alias: alias1
            - name: projectName3
              alias: alias2
              wiqls:
                - wiql3.1
FieldDescriptionRequired
projectsList of the projects✓
nameThe project name as listed under the "Projects" tab when you are logged into Azure DevOps (on the https://dev.azure.com/{your-organization}/ screen)✓
wiqlsList of WIQL conditions to filter work items fetched
aliasAlias for the configuration in Cortex (only needed if you have opted into multi-account support)

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.

Expected results​

Entity pages​

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.

Integrations - Git​

You can access more detailed information pulled from Azure DevOps in the Git tab under Integrations in the sidebar. At the top of the Git 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.

Integrations - Azure DevOps work items​

From the Azure DevOps work items tab, you can find a list of open Azure DevOps work items. Each work item will show the title, summary, assignees, priority, and date created.

Dev homepage​

The Azure DevOps integration enables Cortex to pull information about pull requests and work items into the Dev homepage. You can find your open pull requests under the My open PRs tab, any pull requests assigned to you for review under the Assigned reviews tab, and any work items assigned to you under the Issues tab.

Pull requests and work items from Azure DevOps are refreshed every 5 minutes.

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.

Work items

Number of unresolved work items associated with the entity, where unresolved is defined as the WIQL [System.State] NOT IN ('Closed', 'Done', 'Completed', 'Inactive', 'Removed').

Definition: azureDevops.workItems()

Example

For a Scorecard measuring entity maturity, you can use this expression to make sure entities have fewer than 10 Azure DevOps work items:

azureDevops.workItems().length <= 10
Work items from WIQL query

Number of work items associated with the entity based on arbitrary WIQL query.

Definition: azureDevops.workItems(query: Text | Null)

Example

For a more specific rule in an entity maturity Scorecard, you can use this expression with a WIQL query to make sure entities have no more than 3 tickets with "Doing" status and highest priority.

jira.workItems("System.State = \"Doing\" AND Microsoft.VSTS.Common.Priority = 1").length <= 3

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:

  1. Click Create issue.
  2. 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.
  3. 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.
  4. 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.

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 are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:

  • Email: help@cortex.io, 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.