Skip to main content

Azure DevOps

In this example, we are going to use a script to fetch data from the Azure DevOps API and ingest it into Port.
We will also create a webhook integration between Azure DevOps and Port, which will ingest project, repository, work item and pipeline entities.

Port configurationโ€‹

Create the following blueprint definition:

Project blueprint
{
"identifier": "azure_devops_project",
"description": "A software catalog for Azure DevOps projects",
"title": "Azure Devops Project",
"icon": "AzureDevops",
"schema": {
"properties": {
"description": {
"title": "Description",
"type": "string"
},
"url": {
"title": "URL",
"type": "string",
"format": "url"
},
"visibility": {
"title": "Visibility",
"type": "string"
},
"last_updated_time": {
"title": "Last Updated Time",
"type": "string",
"format": "date-time"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}
Repository blueprint
{
"identifier": "azure_devops_repository",
"description": "A software catalog for Azure Devops repositories",
"title": "Azure Devops Repository",
"icon": "AzureDevops",
"schema": {
"properties": {
"url": {
"title": "URL",
"type": "string",
"format": "url"
},
"default_branch": {
"title": "Default Branch",
"type": "string"
},
"is_disabled": {
"title": "Is Disabled",
"type": "boolean",
"default": false
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {
"project": {
"title": "Project",
"target": "azure_devops_project",
"required": false,
"many": false
}
}
}
Pipeline blueprint
{
"identifier": "azure_devops_pipeline",
"description": "A software catalog for Azure Devops pipeline",
"title": "Azure Devops Pipeline",
"icon": "AzureDevops",
"schema": {
"properties": {
"url": {
"title": "URL",
"type": "string",
"format": "url"
},
"revision": {
"title": "Revision",
"type": "number"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {
"project": {
"title": "Project",
"target": "azure_devops_project",
"required": false,
"many": false
}
}
}
Work item blueprint
{
"identifier": "azure_devops_work_item",
"description": "A software catalog for Azure Devops work item",
"title": "Azure Devops Work Item",
"icon": "AzureDevops",
"schema": {
"properties": {
"url": {
"title": "URL",
"type": "string",
"format": "url",
"icon": "DefaultProperty"
},
"revision": {
"title": "Revision",
"type": "number",
"icon": "DefaultProperty"
},
"type": {
"title": "Type",
"type": "string",
"icon": "DefaultProperty"
},
"state": {
"icon": "DefaultProperty",
"title": "State",
"type": "string",
"enum": ["To Do", "Doing", "Done"],
"enumColors": {
"To Do": "blue",
"Doing": "yellow",
"Done": "green"
}
},
"created_date": {
"title": "Created Date",
"type": "string",
"format": "date-time",
"icon": "DefaultProperty"
},
"created_by": {
"icon": "TwoUsers",
"title": "Created By",
"type": "string"
},
"updated_date": {
"title": "Updated Date",
"type": "string",
"format": "date-time",
"icon": "DefaultProperty"
},
"priority": {
"title": "Priority",
"type": "number",
"icon": "DefaultProperty"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {
"project": {
"title": "Project",
"target": "azure_devops_project",
"required": false,
"many": false
}
}
}

Running the python scriptโ€‹

To ingest data from your Azure DevOps account to Port, run the following commands:

export PORT_CLIENT_ID=<ENTER CLIENT ID>
export PORT_CLIENT_SECRET=<ENTER CLIENT SECRET>
export AZURE_DEVOPS_ORG_ID=<ENTER AZURE DEVOPS ORGANIZATION ID>
export AZURE_DEVOPS_APP_PASSWORD=<ENTER AZURE DEVOPS APP PASSWORD>

git clone https://github.com/port-labs/azure-devops-resources.git

cd azure-devops-resources

pip install -r ./requirements.txt

python app.py

tip

Find more information about the python script here

Follow the official documentation on how to create an azure devops app password.

Port Webhook Configurationโ€‹

Create the following webhook configuration using Port's UI

Webhook configuration
  1. Basic details tab - fill the following details:

    1. Title : Azure DevOps Mapper.
    2. Identifier : azure_devops_mapper.
    3. Description : A webhook configuration to map Azure DevOps resources to Port.
    4. Icon : AzureDevops.
  2. Integration configuration tab - fill the following JQ mapping:

    [
    {
    "blueprint": "azure_devops_work_item",
    "filter": ".body.eventType == \"workitem.created\"",
    "entity": {
    "identifier": ".body.resource.id | tostring",
    "title": ".body.resource.fields.\"System.Title\"",
    "properties": {
    "revision": ".body.resource.rev",
    "url": ".body.resource.url",
    "type": ".body.resource.fields.\"System.WorkItemType\"",
    "state": ".body.resource.fields.\"System.State\"",
    "created_date": ".body.resource.fields.\"System.CreatedDate\"",
    "created_by": ".body.resource.fields.\"System.CreatedBy\"",
    "updated_date": ".body.resource.fields.\"System.ChangedDate\"",
    "priority": ".body.resource.fields.\"Microsoft.VSTS.Common.Priority\""
    },
    "relations": {
    "project": ".body.resourceContainers.project.id"
    }
    }
    },
    {
    "blueprint": "azure_devops_work_item",
    "filter": ".body.eventType == \"workitem.updated\"",
    "entity": {
    "identifier": ".body.resource.workItemId | tostring",
    "title": ".body.resource.revision.fields.\"System.Title\"",
    "properties": {
    "revision": ".body.resource.rev",
    "url": ".body.resource.url",
    "type": ".body.resource.revision.fields.\"System.WorkItemType\"",
    "state": ".body.resource.revision.fields.\"System.State\"",
    "created_date": ".body.resource.revision.fields.\"System.CreatedDate\"",
    "created_by": ".body.resource.revision.fields.\"System.CreatedBy\"",
    "updated_date": ".body.resource.revision.fields.\"System.ChangedDate\"",
    "priority": ".body.resource.revision.fields.\"Microsoft.VSTS.Common.Priority\""
    },
    "relations": {
    "project": ".body.resourceContainers.project.id"
    }
    }
    },
    {
    "blueprint": "azure_devops_pipeline",
    "filter": ".body.eventType | startswith(\"ms.vss-pipelines\")",
    "entity": {
    "identifier": ".body.resource.run.pipeline.id // .body.resource.pipeline.id | tostring",
    "title": ".body.resource.run.pipeline.name // .body.resource.pipeline.name",
    "properties": {
    "url": ".body.resource.run.pipeline.url // .body.resource.pipeline.name",
    "revision": ".body.resource.run.pipeline.revision // .body.resource.pipeline.revision"
    },
    "relations": {
    "project": ".body.resourceContainers.project.id"
    }
    }
    },
    {
    "blueprint": "azure_devops_repository",
    "filter": ".body.eventType == \"git.push\"",
    "entity": {
    "identifier": ".body.resource.repository.id | tostring",
    "title": ".body.resource.repository.name",
    "properties": {
    "url": ".body.resource.repository.url",
    "default_branch": ".body.resource.repository.defaultBranch"
    },
    "relations": {
    "project": ".body.resource.repository.project.id"
    }
    }
    }
    ]
  3. Click Save at the bottom of the page.

Create a webhook in Azure DevOpsโ€‹

  1. From your Azure DevOps account, open the project where you want to add the webhook.
  2. Click Project settings on the left sidebar.
  3. On the General section, select Service hook on the left sidebar.
  4. Click the plus + button to create a webhook for the project.
  5. A pop up page will be shown. Select Web Hooks from the list and click Next.
  6. Under Trigger, select the type of event you want to receive webhook notifications for. The example webhook configuration supports the following events:
    1. Code pushed
    2. Run state changed
    3. Run job state changed
    4. Run stage state changed
    5. Work item created
    6. Work item updated
  7. Leave the Filters section unchanged and click Next.
  8. On the final page (Action Settings), enter the value of the webhook URL you received after creating the webhook configuration in Port in the URL textbox.
  9. Test your webhook subscription and click Finish.

Follow this documentation to learn more about webhook events in Azure DevOps.

Done! Any change that happens to your repository, work item or pipeline in Azure DevOps will trigger a webhook event to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.