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:

Hosted by Port
Real Time & Always On
Scheduled

Using this installation option means that the integration will be hosted by Port, with a customizable resync interval to ingest data into Port.

To install, follow the following steps:

Go to the Data sources page of your portal.
Click on the + Data source button in the top-right corner.
Click on the relevant integration in the list.
Under Select your installation method, choose Hosted by Port.
Configure the integration settings and application settings as you wish (see below for details).

Application settings

Every integration hosted by Port has the following customizable application settings:

Resync interval: The frequency at which Port will ingest data from the integration. There are various options available, ranging from every 1 hour to once a day.
Send raw data examples: A boolean toggle (enabled by default). If enabled, raw data examples will be sent from the integration to Port. These examples are used when testing your mapping configuration, they allow you to run your jq expressions against real data and see the results.

Integration settings

Every integration has its own tool-specific settings, under the Integration settings section.
Each of these settings has an ⓘ icon next to it, which you can hover over to see a description of the setting.

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 changing such a setting, you will be prompted to choose an existing secret or create a new one:

Live event support

Currently, live events are not supported for integrations hosted by Port.
Resyncs will be performed periodically, based on the Resync interval you have configured, or manually triggered by you via Port's UI.

Therefore, real-time events such as GitOps pushes will not be ingested into Port immediately.
Live events are WIP and will be supported in the future.

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.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`	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
`sendRawDataExamples`	Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true

Helm
ArgoCD

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 sendRawDataExamples=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

To install the integration using ArgoCD, follow these steps:

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

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

Apply your application manifest with kubectl:

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

Advanced integration configuration

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

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	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 (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__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.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.

Installation

Create a personal access token​

Configure the integration​

appHost & listening to hooks​

Deploy the integration​

Application settings

Integration settings

Port secrets

Create a personal access token

Configure the integration

`appHost` & listening to hooks

Deploy the integration