Installation

This page details how to install Port's Azure DevOps integration (powered by the Ocean framework). It outlines the following steps:

• How to create a personal access token to give the integration permissions to query your Azure DevOps account.
• How to configure and customize the integration before deploying it.
• How to deploy the integration in the configuration that fits your use case.

Prerequisites

• An Azure DevOps account with admin privileges.
• If you choose the real time & always on installation method, you will need a kubernetes cluster on which to install the integration.
• Your Port user role is set to Admin.

Setup

Create a personal access token

The integration requires a personal access token to authenticate with your Azure DevOps account.
You can create one by following these steps.

The token should either have admin permissions, or read permissions for each of the supported resources you want to ingest into Port.

Deploy the integration

Choose one of the following installation methods:
Not sure which method is right for your use case? Check the available installation methods.

Hosted by Port

1. Go to the AzureDevOps data source page in your portal.

2. Under Select your installation method, choose Hosted by Port.

3. Configure the Installation parameters and Advanced configuration as you wish (see below for details).

Installation parameters

Each integration requires specific parameters (such as an API token, a URL, etc.), as seen in Port's UI when installing it. Hover over the ⓘ icon next to each parameter to see more details about it.

Advanced configuration

• During the installation process each integration may have additional settings under the Advanced configuration section in Port's UI.
  Additionally, each integration has one or more settings that can be configured after installation. To do so, click on the integration's name in the Data sources page and navigate to the Setting tab.
  Hover over the ⓘ icon next to each setting to see more details about it.

• If the integration supports live events, the option to enable/disable them will be available in this section.

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

  Supported live event triggers (click to expand)

  Code Events:

  • git.pullrequest.created
  • git.pullrequest.updated
  • git.push

  Repository:

  • git.repo.created

  Work Item:

  • workitem.created
  • workitem.updated
  • workitem.commented
  • workitem.deleted
  • workitem.restored

  Pipeline Changes:

  • ms.vss-pipelines.run-state-changed-event
  • ms.vss-pipelinechecks-events.approval-completed
  • ms.vss-pipelinechecks-events.approval-pending
  • ms.vss-pipelines.stage-state-changed-event
  • ms.vss-pipelinechecks-events.check-updated-event
  • ms.vss-pipelines.job-state-changed-event

  Advanced Security Alerts:

  • ms.vss-alerts.alert-created-event
  • ms.vss-alerts.alert-state-changed-event
  • ms.vss-alerts.alert-updated-event

Port secrets

Some integration settings require sensitive pieces of data, such as tokens. For these settings, Port secrets will be used, ensuring that your sensitive data is encrypted and secure.

When filling in such a setting, its value will be obscured (shown as ••••••••). For each such setting, Port will automatically create a secret in your organization.

To see all secrets in your organization, follow these steps.

Limitations

• The maximum time for a full sync to run is based on the configured resync interval. For very large amounts of data where a resync operation is expected to take longer, please use a longer interval.

Port source IP addresses

When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses. You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:

• Europe (EU): 54.73.167.226, 63.33.143.237, 54.76.185.219
• United States (US): 3.234.37.33, 54.225.172.136, 3.225.234.99

Live event support

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

Supported live event triggers (click to expand)

Code Events:

• git.pullrequest.created
• git.pullrequest.updated
• git.push

Repository:

• git.repo.created

Work Item:

• workitem.created
• workitem.updated
• workitem.commented
• workitem.deleted
• workitem.restored

Pipeline Changes:

• ms.vss-pipelines.run-state-changed-event
• ms.vss-pipelinechecks-events.approval-completed
• ms.vss-pipelinechecks-events.approval-pending
• ms.vss-pipelines.stage-state-changed-event
• ms.vss-pipelinechecks-events.check-updated-event
• ms.vss-pipelines.job-state-changed-event

Advanced Security Alerts:

• ms.vss-alerts.alert-created-event
• ms.vss-alerts.alert-state-changed-event
• ms.vss-alerts.alert-updated-event

Self-hosted

Using this installation option means that the integration will be able to update Port in real time using webhooks.

Prerequisites

• A Kubernetes cluster - the integration's container chart will be deployed to this cluster.

• kubectl and helm must be installed on your machine. Your kubectl CLI must be connected to the Kubernetes cluster where you plan to install the integration.

For details about the available parameters for the installation, see the table below.

Helm

1. Go to the Azure-devops data source page in your portal.

2. Select the Self-hosted method.

3. A helm command will be displayed, with default values already filled out (e.g. your Port client ID, client secret, etc). Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.

BaseUrl & webhook configuration

To enable real-time updates of the data in your software catalog, you need to define the liveEvents.baseUrl parameter.
This parameter should be set to the URL of your Azure-devops integration instance, which needs to have the option to setup webhooks via HTTP requests/receive HTTP requests, so ensure the network is configured accordingly.

• If Azure-devops and the integration are in the same cluster/network: Use an internal URL (e.g., a Kubernetes service DNS name).
  For Kubernetes deployments, create a service to expose the integration pod and use the service URL as liveEvents.baseUrl. If both the source system and integration are in the same cluster, an internal ClusterIP service is sufficient.
• If Azure-devops is external to the integration's network: The integration must be exposed via an ingress, load balancer, or public URL that Azure-devops can reach.

If liveEvents.baseUrl is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the scheduledResyncInterval parameter has to be set, or a manual resync will need to be triggered through Port's UI.

Debugging local integrations

To test webhooks or live event delivery to your local environment, expose your local pod or service to the internet using ngrok (e.g. ngrok http http://localhost:8000)

Securing Your Webhooks

The integration.secrets.webhookSecret parameter secures your webhooks. If not provided, the integration will process webhooks without validating the source of the events.

Scalable mode for large integrations

If you are deploying the integration at scale and want to decouple the resync process from the live events process (recommended for large or high-throughput environments), you can enable scalable mode by adding the following flags to your Helm install command:

  --set workload.kind="CronJob"  \
  --set workload.cron.resyncTimeoutMinutes=60  \
  --set scheduledResyncInterval="'*/60 * * * *'"  \
  --set liveEvents.worker.enabled=true

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:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

ArgoCD

To install the integration using ArgoCD:

1. Create a values.yaml file in argocd/my-ocean-azure-devops-integration in your git repository with the content:

note

Remember to replace the placeholders for AZURE_PAT, and organizationName.

initializePortResources: true
scheduledResyncInterval: 120
integration:
  identifier: my-ocean-azure-devops-integration
  type: azure-devops
  eventListener:
    type: POLLING
  secrets:
    personalAccessToken: AZURE_PAT
  config:
    organizationUrl: https://dev.azure.com/organizationName

2. Install the my-ocean-azure-devops-integration ArgoCD Application by creating the following my-ocean-azure-devops-integration.yaml manifest:

note

Remember to replace the placeholders for YOUR_PORT_CLIENT_ID YOUR_PORT_CLIENT_SECRET and YOUR_GIT_REPO_URL.

Multiple sources ArgoCD documentation can be found here.

ArgoCD Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-ocean-azure-devops-integration
  namespace: argocd
spec:
  destination:
    namespace: my-ocean-azure-devops-integration
    server: https://kubernetes.default.svc
  project: default
  sources:
  - repoURL: 'https://port-labs.github.io/helm-charts/'
    chart: port-ocean
    targetRevision: 0.9.5
    helm:
      valueFiles:
      - $values/argocd/my-ocean-azure-devops-integration/values.yaml
      parameters:
        - name: port.clientId
          value: YOUR_PORT_CLIENT_ID
        - name: port.clientSecret
          value: YOUR_PORT_CLIENT_SECRET
        - name: port.baseUrl
          value: https://api.port.io
  - repoURL: YOUR_GIT_REPO_URL
    targetRevision: main
    ref: values
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

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:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

1. Apply your application manifest with kubectl:

kubectl apply -f my-ocean-azure-devops-integration.yaml

This table summarizes the available parameters for the installation.

Parameter	Description	Example	Required
port.clientId	Your port client id		✅
port.clientSecret	Your port client secret		✅
port.baseUrl	Your Port API URL - https://api.port.io for EU, https://api.us.port.io for US		✅
integration.secrets.personalAccessToken	The personal access token used to query authenticate with your Azure Devops account		✅
integration.secrets.organizationUrl	The URL of your Azure DevOps organization. Cloud: https://dev.azure.com/{organization}. On-premises: https://{instance}/{collection}	https://dev.azure.com/organizationName	✅
integration.secrets.isProjectsLimited	If using a project-scoped personal access token, this setting is enabled to create webhooks for individual projects. Enabled by default		❌
integration.config.appHost (deprecated)	The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Azure DevOps	https://my-ocean-integration.com	❌
integration.eventListener.type	The event listener type. Read more about event listeners		✅
integration.type	The integration to be installed		✅
scheduledResyncInterval	The number of minutes between each resync. When not set the integration will resync for each event listener resync event. Read more about scheduledResyncInterval		❌
initializePortResources	Default true, When set to true the integration will create default blueprints and the port App config Mapping.		❌
sendRawDataExamples	Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true		❌
integration.secrets.webhookSecret	Webhook secret for authenticating incoming events. Learn more		❌
liveEvents.baseUrl	The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Azure DevOps	https://my-ocean-integration.com	❌

Live event support

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

Supported live event triggers (click to expand)

Code Events:

• git.pullrequest.created
• git.pullrequest.updated
• git.push

Repository:

• git.repo.created

Work Item:

• workitem.created
• workitem.updated
• workitem.commented
• workitem.deleted
• workitem.restored

Pipeline Changes:

• ms.vss-pipelines.run-state-changed-event
• ms.vss-pipelinechecks-events.approval-completed
• ms.vss-pipelinechecks-events.approval-pending
• ms.vss-pipelines.stage-state-changed-event
• ms.vss-pipelinechecks-events.check-updated-event
• ms.vss-pipelines.job-state-changed-event

Advanced Security Alerts:

• ms.vss-alerts.alert-created-event
• ms.vss-alerts.alert-state-changed-event
• ms.vss-alerts.alert-updated-event

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, click here.

Recommended resource sizes

To ensure optimal performance and avoid out-of-memory (OOM) errors, we recommend the following resources for this integration:

• CPU Limit: 800m
• CPU Request: 200m
• Memory Limit: 2Gi
• Memory Request: 2Gi

Set resource values

helm install my-integration port-labs/port-ocean \
# ... other parameters
--set ocean.resources.limits.cpu=800m \
--set ocean.resources.limits.memory=2Gi \
--set ocean.resources.requests.cpu=200m \
--set ocean.resources.requests.memory=2Gi

CI

This pipeline will run the Azure DevOps integration once and then exit, this is useful for scheduled ingestion of data.

Azure Pipeline

Azure pipeline agent check

Your Azure pipeline agent should be able to run docker commands.

Make sure to configure the following variables using Azure DevOps variable groups. Add them into in a variable group named port-ocean-credentials:

Parameter	Description	Example	Required
OCEAN__INTEGRATION__CONFIG__PERSONAL_ACCESS_TOKEN	The personal access token used to query authenticate with your Azure Devops account		✅
OCEAN__INTEGRATION__CONFIG__ORGANIZATION_URL	The URL of your Azure DevOps instance		✅
OCEAN__INTEGRATION__CONFIG__IS_PROJECTS_LIMITED	If using a project-scoped personal access token, this setting is enabled to create webhooks for individual projects. Enabled by default.		❌
OCEAN__PORT__CLIENT_ID	Your Port client id (How to get the credentials)		✅
OCEAN__PORT__CLIENT_SECRET	Your Port client secret (How to get the credentials)		✅
OCEAN__PORT__BASE_URL	Your Port API URL - https://api.port.io for EU, https://api.us.port.io for US		✅
OCEAN__INITIALIZE_PORT_RESOURCES	Default true, When set to true the integration will create default blueprints and the port App config Mapping.		❌
OCEAN__INTEGRATION__IDENTIFIER	The identifier of the integration that will be installed		❌

Here is an example for azure-devops-integration.yml pipeline file:

trigger:
- main

pool:
  vmImage: "ubuntu-latest"

variables:
  - group: port-ocean-credentials


steps:
- script: |
    # Set Docker image and run the container
    integration_type="azure-devops"
    version="latest"

    image_name="ghcr.io/port-labs/port-ocean-$integration_type:$version"
    
    docker run -i --rm --platform=linux/amd64 \
        -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \
        -e OCEAN__INITIALIZE_PORT_RESOURCES=true \
        -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \
        -e OCEAN__INTEGRATION__CONFIG__PERSONAL_ACCESS_TOKEN=${OCEAN__INTEGRATION__CONFIG__PERSONAL_ACCESS_TOKEN} \
        -e OCEAN__INTEGRATION__CONFIG__ORGANIZATION_URL=${OCEAN__INTEGRATION__CONFIG__ORGANIZATION_URL} \
        -e OCEAN__PORT__CLIENT_ID=${OCEAN__PORT__CLIENT_ID} \
        -e OCEAN__PORT__CLIENT_SECRET=${OCEAN__PORT__CLIENT_SECRET} \
        -e OCEAN__PORT__BASE_URL='https://api.port.io' \
        $image_name

    exit $?
  displayName: 'Ingest Azure DevOps Data into Port'

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:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, click here.

Need help?

Having issues with Azure DevOps integration or pipelines? See the Azure DevOps Troubleshooting Guide for step-by-step help.