> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Azure DevOps

AzureDevops iconAzureDevops icon
Loading version...

Port's Azure DevOps integration allows you to model Azure DevOps resources in your software catalog and ingest data into them.

Supported resources External link iconrepositorybranchrepository-policyprojectpull-requestpipelinebuildpipeline-stagepipeline-runuserwork-itemarea-pathboardcolumnreleaserelease-definitionenvironmentrelease-deploymentpipeline-deploymentfilefolderadvanced-security-alertgroupgroup-memberwikiteamtest-runmemberiteration

Core support

Incremental syncClosed betaSee supported resourcesLive eventsSee supported resources
Supported deployments models

This integration supports both Azure DevOps Services (cloud) and Azure DevOps Server (on-premises).

Note: When using the on-premises model, releases and work items are not supported due to API version differences. All other supported resources work the same as the cloud version.

Service principal authentication (via Microsoft Entra ID) is available for Azure DevOps Services (cloud) and works for both single-account and multi-account installations. Azure DevOps Server (on-premises) must continue to use a personal access token.

Prerequisites​

  • An Azure DevOps account with admin privileges.
  • If you choose the self-hosted installation method, you will need a Kubernetes cluster on which to install the integration.
  • Your Port user role is set to Admin.
Backwards compatibility

Existing installations that authenticate with a personal access token and a single organization URL continue to work without any changes. When accountMode is not set, the integration defaults to Single Account mode.

Authentication methods

The integration supports two authentication methods. Choose the one that matches your deployment:

  • Personal access token (PAT): Authenticates against a single Azure DevOps organization (or a single on-premises collection). This is required for Azure DevOps Server (on-premises).
  • Service principal (recommended): Uses a Microsoft Entra ID application to authenticate with your Azure DevOps organization. This is available for Azure DevOps Services (cloud).
Personal access tokens are being retired

Microsoft is retiring global personal access tokens in Azure DevOps on December 1, 2026, after which existing global PATs will stop working. For Azure DevOps Services (cloud), we recommend migrating to service principal authentication, which uses short-lived, Microsoft Entra-backed credentials. See Microsoft's announcement: Retirement of global personal access tokens in Azure DevOps.

Version requirement

Service principal authentication requires Azure DevOps integration version 0.9.0 or later.

We will create a Microsoft Entra ID application, grant it access to each Azure DevOps organization you want to sync, and provide the resulting credentials to the integration. The same flow applies whether you sync a single organization or multiple organizations from one installation.

  1. Register an application in Microsoft Entra ID. Follow Register an application with the Microsoft identity platform. After registration, record the Application (client) ID and the Directory (tenant) ID from the app's Overview page.

  2. Create a client secret. On the app registration, go to Certificates & secrets and create a new client secret. Copy the secret value immediately (it will not be shown again).

  3. Add the service principal to each Azure DevOps organization you want to sync. Follow Use service principals and managed identities in Azure DevOps. For every target organization:

    • Open the organization at https://dev.azure.com/{organization}.
    • Navigate to Organization settings > Users > Add users.
    • Search for the Enterprise Application's display name (the same name as the app registration you created).
    • Assign an access level of Basic or higher. Stakeholder is not sufficient for repository access.

  4. Grant the service principal permission on each project or repository you want to sync. Use the same Azure DevOps permission model you would apply to a user (for example, Project Settings > Permissions or Repository Settings > Security).

  5. Collect the organization URLs you want to sync. Each URL must follow the format https://dev.azure.com/{organization}. For example:

    https://dev.azure.com/my-org
    https://dev.azure.com/another-org

    You will pass these as a list to the integration.

Required permissions (click to expand)
  • Azure DevOps does not use Microsoft Entra ID application permissions. All access control is enforced through the Azure DevOps permission system, so the app registration itself does not need any API permissions configured. See the Microsoft docs for the full explanation.
  • Permissions must be granted separately inside each Azure DevOps organization you sync, using that organization's permission model.
  • Each organization counts as a separate license for the service principal (no multi-organization licensing discount).
  • The service principal must belong to the same Microsoft Entra tenant that each target Azure DevOps organization is connected to. Cross-tenant access requires Microsoft's documented key-vault and certificate workaround.
Sync time grows with organizations

When syncing multiple organizations, Port processes a few at a time in parallel rather than all at once. Azure DevOps also enforces its own API rate limits separately for each organization. As a result, the more organizations you sync, the longer a full resync takes.

Once complete, you will have:

  • A list of organization URLs (for example, https://dev.azure.com/org-a and https://dev.azure.com/org-b).
  • A tenant ID.
  • A client ID.
  • A client secret value.

Provide these four values to the integration using the installation method you chose below.

Setup​

Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.

Choose method

Configuration​

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

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

Default mapping configuration​

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)
deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
- kind: project
  selector:
    query: 'true'
    defaultTeam: 'false'
  port:
    entity:
      mappings:
        identifier: .id | gsub(" "; "")
        blueprint: '"azureDevopsProject"'
        title: .name
        properties:
          state: .state
          revision: .revision
          visibility: .visibility
          defaultTeam: .defaultTeam.name
          link: .url | gsub("_apis/projects/"; "")
- kind: repository
  selector:
    query: 'true'
    includedFiles:
      - README.md
  port:
    entity:
      mappings:
        identifier: .id
        title: .name
        blueprint: '"azureDevopsRepository"'
        properties:
          url: .remoteUrl
          readme: .__includedFiles["README.md"]
          id: .id
          last_activity: .project.lastUpdateTime
        relations:
          project: .project.id | gsub(" "; "")
- kind: repository-policy
  selector:
    query: .type.displayName=="Minimum number of reviewers"
  port:
    entity:
      mappings:
        identifier: .__repository.id
        blueprint: '"azureDevopsRepository"'
        properties:
          minimumApproverCount: .settings.minimumApproverCount
- kind: repository-policy
  selector:
    query: .type.displayName=="Work item linking"
  port:
    entity:
      mappings:
        identifier: .__repository.id
        blueprint: '"azureDevopsRepository"'
        properties:
          workItemLinking: .isEnabled and .isBlocking
- kind: user
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .user.displayName
        blueprint: '"azureDevopsMember"'
        properties:
          url: .user.url
          email: .user.mailAddress
- kind: pull-request
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .repository.id + "/" + (.pullRequestId | tostring)
        blueprint: '"azureDevopsPullRequest"'
        properties:
          status: .status
          createdAt: .creationDate
          leadTimeHours: (.creationDate as $createdAt | .status as $status | .closedDate as $closedAt | ($createdAt | sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime) as $createdTimestamp | ($closedAt | if . == null then null else sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime end) as $closedTimestamp | if $status == "completed" and $closedTimestamp != null then (((($closedTimestamp - $createdTimestamp) / 3600) * 100 | floor) / 100) else null end)
        relations:
          repository: .repository.id
          service:
            combinator: '"and"'
            rules:
            - operator: '"="'
              property: '"ado_repository_id"'
              value: .repository.id
          creator:
            combinator: '"and"'
            rules:
            - operator: '"="'
              property: '"$identifier"'
              value: .createdBy.uniqueName
          reviewers:
            combinator: '"and"'
            rules:
            - operator: '"in"'
              property: '"$identifier"'
              value: '[.reviewers[].uniqueName]'
          azure_devops_reviewers: '[.reviewers[].id]'
          azure_devops_creator: .createdBy.id
- kind: build
  selector:
    query: "true"
  port:
    entity:
      mappings:
        identifier: .__project.id + "/" + (.id | tostring) | gsub(" "; "")
        title: .buildNumber
        blueprint: '"azureDevopsBuild"'
        properties:
          status: .status
          result: .result
          queueTime: .queueTime
          startTime: .startTime
          finishTime: .finishTime
          definitionName: .definition.name
          requestedFor: .requestedFor.displayName
          link: ._links.web.href
        relations:
          pipeline: .__project.id + "/" + (.definition.id | tostring)
- kind: pipeline-stage
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .__project.id + "/" + (.__build.id | tostring) + "/" + (.id | tostring) | gsub(" "; "")
        title: .name
        blueprint: '"azureDevopsPipelineStage"'
        properties:
          state: .state
          result: .result
          startTime: .startTime
          finishTime: .finishTime
          stageType: .type
        relations:
          build: (.__project.id + "/" + (.__build.id | tostring)) | gsub(" "; "")
          pipelineRun: .__project.id + "/" + (.__build.id | tostring) | gsub(" "; "")
- kind: pipeline-run
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .__project.id + "/" + (.__pipeline.id | tostring) + "/" + (.id | tostring) | gsub(" "; "")
        blueprint: '"azureDevopsPipelineRun"'
        properties:
          state: .state
          result: .result
          createdDate: .createdDate
          finishedDate: .finishedDate
          pipelineName: .pipeline.name
        relations:
          pipeline: .__project.id + "/" + (.__pipeline.id | tostring)
- kind: environment
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .project.id + "/" + (.id | tostring) | gsub(" "; "")
        title: .name | tostring
        blueprint: '"azureDevopsEnvironment"'
        properties:
          description: .description
          createdOn: .createdOn
          lastModifiedOn: .lastModifiedOn
        relations: {}
- kind: release-deployment
  selector:
    query: 'true'
    includeRelease: true
  port:
    entity:
      mappings:
        identifier: .releaseDefinition.projectReference.id + "/" + (.release.id | tostring) + "/" + (.id | tostring) | gsub(" "; "")
        title: .release.name + "-" + (.id | tostring) | gsub(" "; "")
        blueprint: '"azureDevopsReleaseDeployment"'
        properties:
          status: .deploymentStatus
          url: .url
          reason: .reason
          startedOn: .startedOn
          completedOn: .completedOn
          requestedBy: .requestedBy.displayName
          operationStatus: .operationStatus
          environment: .releaseEnvironment.name
        relations:
          release: .releaseDefinition.projectReference.id + "/" + (.release.id | tostring) | gsub(" "; "")
- kind: pipeline-deployment
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .__project.id + "/" + (.environmentId | tostring) + "/" + (.id | tostring) | gsub(" "; "")
        title: .requestIdentifier | tostring
        blueprint: '"azureDevopsPipelineDeployment"'
        properties:
          planType: .planType
          stageName: .stageName
          jobName: .jobName
          result: .result
          startTime: .startTime
          finishTime: .finishTime
        relations:
          environment: .__project.id + "/" + (.environmentId | tostring) | gsub(" "; "")
          build: .__project.id + "/" + (.owner.id | tostring) | gsub(" "; "")

Multi-organization mapping​

When the integration runs in multi-organization mode, every ingested entity is enriched with two extra fields that you can reference in JQ:

  • __organizationUrl: the full URL of the Azure DevOps organization the entity came from (for example, https://dev.azure.com/org-a).
  • __organizationName: the short organization name extracted from that URL (for example, org-a).

Use these fields to disambiguate entities that share an ID across organizations, or to surface the source organization on each entity.

Example multi-organization mapping (click to expand)
resources:
- kind: project
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .__organizationName + "/" + (.id | gsub(" "; ""))
        blueprint: '"azureDevopsProject"'
        title: .__organizationName + " / " + .name
        properties:
          organization: .__organizationName
          organizationUrl: .__organizationUrl
          state: .state
          visibility: .visibility
- kind: repository
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .__organizationName + "/" + .id
        title: .__organizationName + " / " + .name
        blueprint: '"azureDevopsRepository"'
        properties:
          url: .remoteUrl
          organization: .__organizationName
          organizationUrl: .__organizationUrl
        relations:
          project: .__organizationName + "/" + (.project.id | gsub(" "; ""))

The default mapping above continues to work for single-organization installations without any changes. Add the snippet above only if you use the service principal authentication method and sync multiple organizations.

Mapping & selectors per resource​

Use the explorer below to view sample payloads and the resulting Port entities for each resource type. For additional resources and advanced configurations, see the examples page.

To connect work items to area paths (and optionally teams), see Connect work items and teams to area paths.

Set up live events​

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Note that different events are supported depending on the resource type.

Live events base URL

For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.

Call the endpoint with your integration's identifier:

curl -X GET \
  'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
  -H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

In the response, look for the following fields under spec.appSpec:

{
  "spec": {
    "appSpec": {
      "liveEventsUuid": "abcdefghijk",
      "liveEventsIngestHostname": "ingest.ocean.getport.io"
    }
  }
}

Combine them to build the live events base URL:

https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>

For example, with the values above, the live events base URL is:

https://ingest.ocean.getport.io/live-events/abcdefghijk

This is the same URL configured for the integration.

Organization-level service hooks

When isProjectsLimited is false, the integration creates organization-level Azure DevOps service hooks. Only the following hooks are subscribed:

Organization-level hooks (click to expand)
organizationLevel:
  tfs:
    - git.pullrequest.created
    - git.pullrequest.updated
    - git.push
    - workitem.created
    - workitem.updated
    - workitem.commented
    - workitem.deleted
    - workitem.restored
    - build.complete
  rm:
    - ms.vss-release.release-created-event
    - ms.vss-release.release-abandoned-event
    - ms.vss-release.deployment-started-event
    - ms.vss-release.deployment-completed-event

Azure DevOps release service hooks use the rm publisher and are resolved through Azure DevOps's release host, vsrm.dev.azure.com.

Incremental sync​

In addition to the standard full resync, this integration supports incremental sync for the following resource kinds:

  • work-item
  • release
  • build
  • release-deployment
  • pipeline-run
    For incremental sync of pipeline-run, the integration discovers completed runs via the Analytics OData API (analytics.*). Ensure the following: Full resync for pipeline runs uses the Pipelines Runs REST API and does not require Analytics.
  • advanced-security-alert

Any other kind in your mapping is not fetched incrementally, and continues to be kept up to date by the full resync.

See Incremental sync for how it works, its current limitations, and how to enable it for your organization.

Capabilities​

Refer to the capabilities page for optional features such as file ingestion, area path configuration, and multi-entity file parsing. See also Incremental sync above for syncing recently changed resources on a short interval.

Monitoring and sync status​

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Examples​

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

Relevant Guides​

For relevant guides and examples, see the guides section.

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.