diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx index db032f6d68..7657fbac28 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx @@ -1,4 +1,5 @@ - [`repository`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/repositories/list?view=azure-devops-rest-7.2&tabs=HTTP#gitrepository) +- [`branch`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/refs/list?view=azure-devops-rest-7.1#gitref) - [`repository-policy`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/policy-configurations/get?view=azure-devops-rest-7.1#policyconfiguration) - [`project`](https://learn.microsoft.com/en-us/rest/api/azure/devops/core/projects/list?view=azure-devops-rest-7.1&tabs=HTTP#teamprojectreference) - [`pull-request`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests?view=azure-devops-rest-7.1&tabs=HTTP#gitpullrequest) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md index 9b3a5550fd..e5f0177946 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md @@ -1082,8 +1082,46 @@ Here is an example of the payload structure from Azure DevOps: +
+Branch response data (click to expand) +```json showLineNumbers +{ + "name": "refs/heads/feature/new-feature", + "objectId": "ffe9cba521f00d7f60e322845072238635edb451", + "creator": { + "displayName": "Normal Paulk", + "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/ac5aaba6-a66a-4e1d-b508-b060ec624fa9", + "_links": { + "avatar": { + "href": "https://dev.azure.com/fabrikam/_apis/GraphProfile/MemberAvatars/aad.YmFjMGYyZDctNDA3ZC03OGRhLTlhMjUtNmJhZjUwMWFjY2U5" + } + }, + "id": "ac5aaba6-a66a-4e1d-b508-b060ec624fa9", + "uniqueName": "dev@mailserver.com", + "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=ac5aaba6-a66a-4e1d-b508-b060ec624fa9", + "descriptor": "aad.YmFjMGYyZDctNDA3ZC03OGRhLTlhMjUtNmJhZjUwMWFjY2U5" + }, + "url": "https://dev.azure.com/fabrikam/7484f783-66a3-4f27-b7cd-6b08b0b077ed/_apis/git/repositories/d3d1760b-311c-4175-a726-20dfc6a7f885/refs?filter=heads%2Ffeature%2Fnew-feature", + "__repository": { + "id": "d3d1760b-311c-4175-a726-20dfc6a7f885", + "name": "my-repository", + "url": "https://dev.azure.com/fabrikam/7484f783-66a3-4f27-b7cd-6b08b0b077ed/_apis/git/repositories/d3d1760b-311c-4175-a726-20dfc6a7f885", + "webUrl": "https://dev.azure.com/fabrikam/7484f783-66a3-4f27-b7cd-6b08b0b077ed/_git/my-repository", + "project": { + "id": "7484f783-66a3-4f27-b7cd-6b08b0b077ed", + "name": "My Project", + "url": "https://dev.azure.com/fabrikam/_apis/projects/7484f783-66a3-4f27-b7cd-6b08b0b077ed", + "state": "wellFormed", + "revision": 12, + "visibility": "public", + "lastUpdateTime": "2025-05-04T09:34:21.397Z" + } + } +} +``` +
### Mapping Result @@ -1281,7 +1319,7 @@ The combination of the sample payload and the Ocean configuration generates the
- Iteration entity in Port + Iteration entity in Port (Click to expand) ```json showLineNumbers { @@ -1301,8 +1339,26 @@ The combination of the sample payload and the Ocean configuration generates the
+
+Branch entity in Port (Click to expand) +```json showLineNumbers +{ + "identifier": "7b3d6f8480e87f728ebce5378322c6a77d3fv19d", + "title": "refs/heads/feature/new-feature", + "blueprint": "branch", + "properties": { + "repositoryName": "my-repository", + "projectName": "My Project", + "link": "https://dev.azure.com/fabrikam/7484f783-66a3-4f27-b7cd-6b08b0b077ed/_git/my-repository?version=GBrefs/heads/feature/new-feature" + }, + "relations": { + "repository": "myproject/my-repository" + } +} +``` +
## Relevant Guides For relevant guides and examples, see the [guides section](https://docs.port.io/guides?tags=AzureDevops). diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/example-branch/_azuredevops_exporter_example_branch_blueprint.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/example-branch/_azuredevops_exporter_example_branch_blueprint.mdx new file mode 100644 index 0000000000..598a7fedc8 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/example-branch/_azuredevops_exporter_example_branch_blueprint.mdx @@ -0,0 +1,47 @@ +
+Branch blueprint (click to expand) + +```json showLineNumbers +{ + "identifier": "branch", + "title": "Branch", + "icon": "AzureDevops", + "schema": { + "properties": { + "repositoryName": { + "title": "Repository Name", + "type": "string", + "icon": "AzureDevops", + "description": "The name of the repository that contains this branch" + }, + "projectName": { + "title": "Project Name", + "type": "string", + "icon": "AzureDevops", + "description": "The name of the project that contains this branch" + }, + "link": { + "title": "Link", + "type": "string", + "format": "url", + "icon": "Link", + "description": "Link to the branch in Azure DevOps" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "repository": { + "title": "Repository", + "target": "service", + "required": false, + "many": false + } + } +} +``` + +
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/example-branch/_azuredevops_exporter_example_branch_port_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/example-branch/_azuredevops_exporter_example_branch_port_app_config.mdx new file mode 100644 index 0000000000..b486cb89e5 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/example-branch/_azuredevops_exporter_example_branch_port_app_config.mdx @@ -0,0 +1,43 @@ +
+Integration mapping (click to expand) + +```yaml showLineNumbers +resources: + - kind: repository + selector: + query: 'true' + port: + entity: + mappings: + identifier: >- + "\(.project.name | ascii_downcase | gsub("[ ();]"; ""))/\(.name | ascii_downcase | gsub("[ ();]"; ""))" + title: .name + blueprint: '"service"' + properties: + url: .remoteUrl + readme: file://README.md + id: .id + last_activity: .project.lastUpdateTime + relations: + project: .project.id | gsub(" "; "") + - kind: branch + selector: + query: 'true' + port: + entity: + mappings: + identifier: .objectId + title: .name + blueprint: '"branch"' + properties: + repositoryName: .__repository.name + projectName: .__repository.project.name + link: .__repository.webUrl + "?version=GB" + .name + relations: + repository: >- + "\(.__repository.project.name | ascii_downcase | gsub("[ ();]"; + ""))/\(.__repository.name | ascii_downcase | gsub("[ ();]"; ""))" + +``` + +
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/examples.md index 0657ad30fa..2d18c13e23 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/examples.md @@ -47,6 +47,9 @@ import PortPipelineRunAppConfig from './example-pipeline-run/\_azuredevops_expor import IterationBlueprint from './example-iteration/\_azuredevops_exporter_example_iteration_blueprint.mdx' import PortIterationAppConfig from './example-iteration/\_azuredevops_exporter_example_iteration_port_app_config.mdx' +import BranchBlueprint from './example-branch/\_azuredevops_exporter_example_branch_blueprint.mdx' +import PortBranchAppConfig from './example-branch/\_azuredevops_exporter_example_branch_port_app_config.mdx' + import EnvironmentBlueprint from './example-environment/\_azuredevops_exporter_example_environment_blueprint.mdx' import PortEnvironmentAppConfig from './example-environment/\_azuredevops_exporter_example_environment_port_app_config.mdx' @@ -212,6 +215,27 @@ You can use the following Port blueprint definitions and integration configurati After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your iterations. +## Mapping branches + +The following example demonstrates how to ingest your Azure DevOps branches to Port. +You can use the following Port blueprint definitions and integration configuration: + + + + + + + +:::tip To Learn more + +- Refer to the [setup](azure-devops.md#setup) section to learn more about the integration configuration setup process. +- We leverage [JQ JSON processor](https://stedolan.github.io/jq/manual/) to map and transform Azure DevOps objects to Port entities. +- Click [Here](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/refs/list?view=azure-devops-rest-7.1#gitref) for the Azure DevOps refs object structure. + +::: + +After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your branches. + ## Mapping test runs