Skip to main content

Azure DevOps

Our integration with Azure DevOps allows you to export objects to Port as entities of existing blueprints. The integration supports real-time event processing so Port always provides an accurate real-time representation of your Azure DevOps resources.

Common use cases​

Our Azure DevOps integration makes it easy to fill the software catalog with data directly from your organization, for example:

  • Map most of the resources in the organization, including projects, repositories, pipelines, pull requests, teams and members.
  • Watch for Azure DevOps object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
  • Manage Port entities using GitOps.

Installation​

To install Port's Azure DevOps integration, follow the installation guide.

Ingesting Git objects​

This integration allows you to ingest a variety of objects resources provided by the Azure DevOps API. It allows you to perform ETL operations on data from the Azure DevOps API into the desired data model.

This integration uses a YAML configuration to describe the ETL process to load data into the developer portal. The approach reflects a golden middle between an overly opinionated Git visualization that might not work for everyone and a too-broad approach that could introduce unneeded complexity into the developer portal.

Here is an example snippet from the config which demonstrates the ETL process for getting pull-request data from Azure DevOps into the software catalog:

resources:
  # Extract
  - kind: pull-request
    selector:
      query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
    port:
      entity:
        mappings:
          # Transform & Load
          identifier: >-
            .repository.project.name + "/" + .repository.name + (.pullRequestId
            | tostring)
          blueprint: '"azureDevopsPullRequest"'
          properties:
            creator: .createdBy.uniqueName
            status: .status
            reviewers: '[.reviewers[].uniqueName]'
            createdAt: .creationDate
          relations:
            service: .repository.project.name + "/" + .repository.name

The integration makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the different Azure DevOps API routes.

Integration configuration​

The integration's configuration is how you specify the exact resources you want to query from your organization, and which entities and properties you want to fill with the received data.

Here is an example for the integration configuration block:

resources:
  - kind: repository
    selector:
      query: 'true' # JQ boolean query. If evaluated to false - skip syncing the object.
    port:
      entity:
        mappings:
          identifier: .project.name + "/" + .name # The Entity identifier will be the repository name.
          title: .name
          blueprint: '"azureDevopsRepository"'
          properties:
            url: .url
            readme: file://README.md

Configuration structure​

  • The root key of the integration configuration is the resources key:

    resources:
      - kind: repository
        selector:
        ...

  • The kind key is a specifier for an object from the Azure DevOps API:

      resources:
        - kind: repository
          selector:
          ...
    Available Azure DevOps resources

    The following resources can be used to map data from Azure DevOps, it is possible to reference any field that appears in the API responses linked below for the Azure Devops integration api reference.

Filtering unwanted objects​

The selector and the query keys let you filter exactly which objects from the specified kind will be ingested to the software catalog:

resources:
  - kind: repository
    selector:
      query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
    port:

For example, to ingest only repositories that have a name starting with "service", use the query key like this:

query: .name | startswith("service")

The port, entity and the mappings keys open the section used to map the Azure DevOps API object fields to Port entities. To create multiple mappings of the same kind, you can add another item to the resources array;

resources:
  - kind: repository
    selector:
      query: "true"
    port:
      entity:
        mappings: # Mappings between one Azure DevOps API object to a Port entity. Each value is a JQ query.
          identifier: .project.name + "/" + .name
          title: .name
          blueprint: '"azureDevopsRepository"'
          properties:
            url: .url
            readme: file://README.md
  - kind: repository # In this instance project is mapped again with a different filter
    selector:
      query: '.name == "MyRepositoryName"'
    port:
      entity:
        mappings: ...
tip

Pay attention to the value of the blueprint key, if you want to use a hardcoded string, you need to encapsulate it in 2 sets of quotes, for example use a pair of single-quotes (') and then another pair of double-quotes (")

Permissions​

Port's Azure DevOps integration requires a personal access token, follow the instructions in the installation guide.

Examples​

Refer to the examples page for practical configurations and their corresponding blueprint definitions.

GitOps​

Port's Azure DevOps integration also provides GitOps capabilities, refer to the GitOps page to learn more.

Advanced​

Refer to the advanced page for advanced use cases and examples.