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.

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.

Configure the integration

appHost & listening to hooks

tip

The appHost parameter is used specifically to enable the real-time functionality of the integration.

If it 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.

In order for the Azure Devops integration to update the data in Port on every change in the Azure Devops repository, you need to specify the appHost parameter. The appHost parameter should be set to the url of your Azure Devops integration instance. In addition, your Azure Devops instance (whether it is Azure Devops SaaS or a self-hosted version of Azure Devops) needs to have the option to send webhook requests to the Azure Devops integration instance, so please configure your network accordingly.

Deploy the integration

Choose one of the following installation methods:

Real Time & Always On

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

This table summarizes the available parameters for the installation. Set them as you wish in the script below, then copy it and run it in your terminal:

Parameter	Description	Example	Required
port.clientId	Your port client id		✅
port.clientSecret	Your port client secret		✅
port.baseUrl	Your Port API URL - https://api.getport.io for EU, https://api.us.getport.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	https://dev.azure.com/organizationName	✅
integration.config.appHost	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	❌

Advanced configuration

Parameter	Description
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. Read more about initializePortResources

Helm

To install the integration using Helm, run the following command:

helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install my-azure-devops-integration port-labs/port-ocean \
	--set port.clientId="PORT_CLIENT_ID"  \
	--set port.clientSecret="PORT_CLIENT_SECRET"  \
	--set port.baseUrl="https://api.getport.io"  \
	--set initializePortResources=true  \
	--set scheduledResyncInterval=120 \
	--set integration.identifier="my-azure-devops-integration"  \
	--set integration.type="azure-devops"  \
	--set integration.eventListener.type="POLLING"  \
	--set integration.secrets.organizationUrl="https://dev.azure.com/organizationName"  \
	--set integration.secrets.personalAccessToken="Enter value here"

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

• If you use the EU region of Port, available at https://app.getport.io, your Port API URL is https://api.getport.io
• If you use the US region of Port, available at https://app.us.getport.io, your Port API URL is https://api.us.getport.io

ArgoCD

To install the integration using ArgoCD, follow these steps:

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.1.14
    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.getport.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 baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

• If you use the EU region of Port, available at https://app.getport.io, your Port API URL is https://api.getport.io
• If you use the US region of Port, available at https://app.us.getport.io, your Port API URL is https://api.us.getport.io

1. Apply your application manifest with kubectl:

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

Scheduled

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__PORT__CLIENT_ID	Your Port client (How to get the credentials) id		✅
OCEAN__PORT__CLIENT_SECRET	Your Port client (How to get the credentials) secret		✅
OCEAN__PORT__BASE_URL	Your Port API URL - https://api.getport.io for EU, https://api.us.getport.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. Read more about initializePortResources		❌
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__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.getport.io' \
        $image_name

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

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

• If you use the EU region of Port, available at https://app.getport.io, your Port API URL is https://api.getport.io
• If you use the US region of Port, available at https://app.us.getport.io, your Port API URL is https://api.us.getport.io

Advanced integration configuration

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