Skip to content

Commit e5b893e

Browse files
sivanel97sivanel97
authored
Merge pull request #2903 from port-labs/PORT-16589
Added documenation for branch support in azure devops
2 parents e5414a6 + c092121 commit e5b893e

File tree

5 files changed

+172
-1
lines changed

5 files changed

+172
-1
lines changed

‎docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
- [`repository`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/repositories/list?view=azure-devops-rest-7.2&tabs=HTTP#gitrepository)
2+
- [`branch`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/refs/list?view=azure-devops-rest-7.1#gitref)
23
- [`repository-policy`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/policy-configurations/get?view=azure-devops-rest-7.1#policyconfiguration)
34
- [`project`](https://learn.microsoft.com/en-us/rest/api/azure/devops/core/projects/list?view=azure-devops-rest-7.1&tabs=HTTP#teamprojectreference)
45
- [`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)

‎docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md‎

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1082,8 +1082,46 @@ Here is an example of the payload structure from Azure DevOps:
10821082

10831083
</details>
10841084

1085+
<details>
1086+
<summary><b>Branch response data (click to expand)</b></summary>
10851087

1088+
```json showLineNumbers
1089+
{
1090+
"name": "refs/heads/feature/new-feature",
1091+
"objectId": "ffe9cba521f00d7f60e322845072238635edb451",
1092+
"creator": {
1093+
"displayName": "Normal Paulk",
1094+
"url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/ac5aaba6-a66a-4e1d-b508-b060ec624fa9",
1095+
"_links": {
1096+
"avatar": {
1097+
"href": "https://dev.azure.com/fabrikam/_apis/GraphProfile/MemberAvatars/aad.YmFjMGYyZDctNDA3ZC03OGRhLTlhMjUtNmJhZjUwMWFjY2U5"
1098+
}
1099+
},
1100+
"id": "ac5aaba6-a66a-4e1d-b508-b060ec624fa9",
1101+
"uniqueName": "dev@mailserver.com",
1102+
"imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=ac5aaba6-a66a-4e1d-b508-b060ec624fa9",
1103+
"descriptor": "aad.YmFjMGYyZDctNDA3ZC03OGRhLTlhMjUtNmJhZjUwMWFjY2U5"
1104+
},
1105+
"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",
1106+
"__repository": {
1107+
"id": "d3d1760b-311c-4175-a726-20dfc6a7f885",
1108+
"name": "my-repository",
1109+
"url": "https://dev.azure.com/fabrikam/7484f783-66a3-4f27-b7cd-6b08b0b077ed/_apis/git/repositories/d3d1760b-311c-4175-a726-20dfc6a7f885",
1110+
"webUrl": "https://dev.azure.com/fabrikam/7484f783-66a3-4f27-b7cd-6b08b0b077ed/_git/my-repository",
1111+
"project": {
1112+
"id": "7484f783-66a3-4f27-b7cd-6b08b0b077ed",
1113+
"name": "My Project",
1114+
"url": "https://dev.azure.com/fabrikam/_apis/projects/7484f783-66a3-4f27-b7cd-6b08b0b077ed",
1115+
"state": "wellFormed",
1116+
"revision": 12,
1117+
"visibility": "public",
1118+
"lastUpdateTime": "2025-05-04T09:34:21.397Z"
1119+
}
1120+
}
1121+
}
1122+
```
10861123

1124+
</details>
10871125

10881126
### Mapping Result
10891127

@@ -1281,7 +1319,7 @@ The combination of the sample payload and the Ocean configuration generates the
12811319

12821320

12831321
<details>
1284-
<summary> Iteration entity in Port </summary>
1322+
<summary><b> Iteration entity in Port (Click to expand)</b></summary>
12851323

12861324
```json showLineNumbers
12871325
{
@@ -1301,8 +1339,26 @@ The combination of the sample payload and the Ocean configuration generates the
13011339

13021340
</details>
13031341

1342+
<details>
1343+
<summary><b>Branch entity in Port (Click to expand)</b></summary>
13041344

1345+
```json showLineNumbers
1346+
{
1347+
"identifier": "7b3d6f8480e87f728ebce5378322c6a77d3fv19d",
1348+
"title": "refs/heads/feature/new-feature",
1349+
"blueprint": "branch",
1350+
"properties": {
1351+
"repositoryName": "my-repository",
1352+
"projectName": "My Project",
1353+
"link": "https://dev.azure.com/fabrikam/7484f783-66a3-4f27-b7cd-6b08b0b077ed/_git/my-repository?version=GBrefs/heads/feature/new-feature"
1354+
},
1355+
"relations": {
1356+
"repository": "myproject/my-repository"
1357+
}
1358+
}
1359+
```
13051360

1361+
</details>
13061362

13071363
## Relevant Guides
13081364
For relevant guides and examples, see the [guides section](https://docs.port.io/guides?tags=AzureDevops).

‎docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/example-branch/_azuredevops_exporter_example_branch_blueprint.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<details>
2+
<summary><b>Branch blueprint (click to expand)</b></summary>
3+
4+
```json showLineNumbers
5+
{
6+
"identifier": "branch",
7+
"title": "Branch",
8+
"icon": "AzureDevops",
9+
"schema": {
10+
"properties": {
11+
"repositoryName": {
12+
"title": "Repository Name",
13+
"type": "string",
14+
"icon": "AzureDevops",
15+
"description": "The name of the repository that contains this branch"
16+
},
17+
"projectName": {
18+
"title": "Project Name",
19+
"type": "string",
20+
"icon": "AzureDevops",
21+
"description": "The name of the project that contains this branch"
22+
},
23+
"link": {
24+
"title": "Link",
25+
"type": "string",
26+
"format": "url",
27+
"icon": "Link",
28+
"description": "Link to the branch in Azure DevOps"
29+
}
30+
},
31+
"required": []
32+
},
33+
"mirrorProperties": {},
34+
"calculationProperties": {},
35+
"aggregationProperties": {},
36+
"relations": {
37+
"repository": {
38+
"title": "Repository",
39+
"target": "service",
40+
"required": false,
41+
"many": false
42+
}
43+
}
44+
}
45+
```
46+
47+
</details>

‎docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/example-branch/_azuredevops_exporter_example_branch_port_app_config.mdx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<details>
2+
<summary><b>Integration mapping (click to expand)</b></summary>
3+
4+
```yaml showLineNumbers
5+
resources:
6+
- kind: repository
7+
selector:
8+
query: 'true'
9+
port:
10+
entity:
11+
mappings:
12+
identifier: >-
13+
"\(.project.name | ascii_downcase | gsub("[ ();]"; ""))/\(.name | ascii_downcase | gsub("[ ();]"; ""))"
14+
title: .name
15+
blueprint: '"service"'
16+
properties:
17+
url: .remoteUrl
18+
readme: file://README.md
19+
id: .id
20+
last_activity: .project.lastUpdateTime
21+
relations:
22+
project: .project.id | gsub(" "; "")
23+
- kind: branch
24+
selector:
25+
query: 'true'
26+
port:
27+
entity:
28+
mappings:
29+
identifier: .objectId
30+
title: .name
31+
blueprint: '"branch"'
32+
properties:
33+
repositoryName: .__repository.name
34+
projectName: .__repository.project.name
35+
link: .__repository.webUrl + "?version=GB" + .name
36+
relations:
37+
repository: >-
38+
"\(.__repository.project.name | ascii_downcase | gsub("[ ();]";
39+
""))/\(.__repository.name | ascii_downcase | gsub("[ ();]"; ""))"
40+
41+
```
42+
43+
</details>

‎docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/examples.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,9 @@ import PortPipelineRunAppConfig from './example-pipeline-run/\_azuredevops_expor
4747
import IterationBlueprint from './example-iteration/\_azuredevops_exporter_example_iteration_blueprint.mdx'
4848
import PortIterationAppConfig from './example-iteration/\_azuredevops_exporter_example_iteration_port_app_config.mdx'
4949

50+
import BranchBlueprint from './example-branch/\_azuredevops_exporter_example_branch_blueprint.mdx'
51+
import PortBranchAppConfig from './example-branch/\_azuredevops_exporter_example_branch_port_app_config.mdx'
52+
5053
import EnvironmentBlueprint from './example-environment/\_azuredevops_exporter_example_environment_blueprint.mdx'
5154
import PortEnvironmentAppConfig from './example-environment/\_azuredevops_exporter_example_environment_port_app_config.mdx'
5255

@@ -212,6 +215,27 @@ You can use the following Port blueprint definitions and integration configurati
212215

213216
After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your iterations.
214217

218+
## Mapping branches
219+
220+
The following example demonstrates how to ingest your Azure DevOps branches to Port.
221+
You can use the following Port blueprint definitions and integration configuration:
222+
223+
<RepositoryBlueprint/>
224+
225+
<BranchBlueprint/>
226+
227+
<PortBranchAppConfig/>
228+
229+
:::tip To Learn more
230+
231+
- Refer to the [setup](azure-devops.md#setup) section to learn more about the integration configuration setup process.
232+
- We leverage [JQ JSON processor](https://stedolan.github.io/jq/manual/) to map and transform Azure DevOps objects to Port entities.
233+
- 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.
234+
235+
:::
236+
237+
After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your branches.
238+
215239
## Mapping test runs
216240
<Tabs groupId="config" queryString="parameter">
217241

0 commit comments

Comments
 (0)