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) | gsub(" "; "")
          blueprint: '"azureDevopsPullRequest"'
          properties:
            creator: .createdBy.uniqueName
            status: .status
            reviewers: '[.reviewers[].uniqueName]'
            createdAt: .creationDate
          relations:
            repository: '.repository.project.name + "/" + .repository.name | gsub(" "; "")'

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.

  • repository
  • repository-policy
  • project
  • pull-request
  • pipeline
  • team
  • member
  • work-item
  • board
  • release

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")

WIQL Support

The Ocean Azure DevOps integration supports querying objects from the work-item kind using WIQL, providing fine-grained control over which work items are ingested into Port.

To leverage WIQL filtering, add a wiql key with your WIQL query as the value within the selector object. For example:

resources:
  - kind: work-item  # WIQL filtering can only be used with the "work-item" kind
    selector:
      query: "true" 
      wiql: "[System.WorkItemType] = 'Task' AND [System.State] = 'Active'"  # WIQL query, will only ingest work items of type "Task" whose state is "Active"
    port:

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 | gsub(" "; "")'
          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.