Skip to content

Commit d362449

Browse files
hadar-cohadar-co
authored
Merge pull request #2579 from port-labs/PORTN-3058-create-a-guide-for-mapping-github-gitlab-and-ado-user-to-a-port-user
PORTN-3058 Add new guide for mapping Git users to Port accounts
2 parents d1b0030 + b3ebc2d commit d362449

File tree

3 files changed

+339
-5
lines changed

3 files changed

+339
-5
lines changed

‎docs/guides/all/map-git-users-to-port-accounts.md‎

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
---
2+
displayed_sidebar: null
3+
description: Automatically map GitHub, GitLab, and Azure DevOps users to their Port user accounts for seamless integration
4+
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
# Map Git users to Port user accounts
9+
10+
This guide demonstrates how to automatically map Git users to existing Port user accounts based on email addresses.
11+
12+
Once implemented, users will be able to:
13+
- Maintain a complete inventory of all Git users in your organization within Port.
14+
- Automatically link Git users to their corresponding Port user accounts for seamless integration.
15+
- Provide visibility into which Git users have Port accounts and which ones do not.
16+
17+
## Prerequisites
18+
19+
This guide assumes the following:
20+
- You have a Port account and have completed the [onboarding process](https://docs.port.io/getting-started/overview).
21+
- You have the relevant Git integration installed and configured:
22+
- [Port's GitHub integrtion](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/).
23+
- [Port's GitLab integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/).
24+
- [Port's Azure DevOps integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/).
25+
- You have permissions to create automations in Port.
26+
27+
## Set up data model
28+
29+
The relations between Git users and Port users are created automatically when we install the relevant Git integrations.
30+
If you haven't installed them yet, please do so first.
31+
32+
<h3>Optional: Add mirror properties to the Port User blueprint</h3>
33+
34+
If you want to display some Git user attributes e.g. username, email, etc. in the Port User blueprint, you can add a mirror property to the Port User blueprint.
35+
36+
Follow the steps below to add a mirror property to the Port User blueprint:
37+
38+
1. Go to the [data model](https://app.getport.io/settings/data-model) page of your portal.
39+
40+
2. Find the `User` blueprint and click on it.
41+
42+
3. Click on the `Edit JSON` button in the top right corner.
43+
44+
4. Add the following mirror properties to the `mirrorProperties` object to display Git user information:
45+
46+
<details>
47+
<summary><b>Port User blueprint mirror properties (Click to expand)</b></summary>
48+
49+
```json showLineNumbers
50+
"mirrorProperties": {
51+
"github_login": {
52+
"title": "GitHub login",
53+
"path": "githubUser.login"
54+
},
55+
"gitlab_username": {
56+
"title": "GitLab username",
57+
"path": "gitlabUser.username"
58+
},
59+
"azuredevops_display_name": {
60+
"title": "Azure DevOps display name",
61+
"path": "azureDevopsUser.displayName"
62+
}
63+
}
64+
```
65+
66+
</details>
67+
68+
5. Click on `Save` to update the blueprint.
69+
70+
:::info Additional mirror properties
71+
You can add more mirror properties to display other Git user attributes or customize which properties are most relevant for your organization. Only add the mirror properties for the Git platforms you're using.
72+
:::
73+
74+
## Implementation
75+
76+
Now we'll update the integration mapping to include the relation and create automations to sync Git users when a new Port user is added.
77+
78+
<Tabs>
79+
<TabItem value="github" label="GitHub" default>
80+
81+
To update the GitHub integration mapping, follow the steps below:
82+
83+
1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page.
84+
85+
2. Find your GitHub integration and click on it.
86+
87+
3. In the mapping configuration, add a new mapping for Port User entities to establish the relation with GitHub users:
88+
89+
<details>
90+
<summary><b>Updated GitHub integration mapping (Click to expand)</b></summary>
91+
92+
```yaml showLineNumbers
93+
# Keep existing githubUser mapping
94+
- kind: user
95+
selector:
96+
query: 'true'
97+
port:
98+
entity:
99+
mappings:
100+
identifier: .login
101+
title: .login
102+
blueprint: '"githubUser"'
103+
properties:
104+
email: .email
105+
106+
# Add new mapping for Port Users with relation to GitHub users
107+
// highlight-start
108+
- kind: user
109+
selector:
110+
query: '.email != null'
111+
port:
112+
entity:
113+
mappings:
114+
identifier: .email
115+
blueprint: '"_user"'
116+
relations:
117+
githubUser: .login
118+
// highlight-end
119+
```
120+
121+
</details>
122+
123+
4. Click on `Save & Resync` to apply the changes
124+
125+
</TabItem>
126+
127+
<TabItem value="gitlab" label="GitLab">
128+
129+
To update the GitLab integration mapping, follow the steps below:
130+
131+
1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page.
132+
133+
2. Find your GitLab integration and click on it.
134+
135+
3. In the mapping configuration, add a new mapping for Port User entities to establish the relation with GitLab users:
136+
137+
<details>
138+
<summary><b>Updated GitLab integration mapping (Click to expand)</b></summary>
139+
140+
```yaml showLineNumbers
141+
# Keep existing gitlabMember mapping
142+
- kind: member
143+
selector:
144+
query: 'true'
145+
port:
146+
entity:
147+
mappings:
148+
identifier: .username
149+
title: .name
150+
blueprint: '"gitlabMember"'
151+
properties:
152+
url: .web_url
153+
state: .state
154+
email: .email
155+
locked: .locked
156+
157+
# Add new mapping for Port Users with relation to GitLab users
158+
// highlight-start
159+
- kind: member
160+
selector:
161+
query: '.email != null'
162+
port:
163+
entity:
164+
mappings:
165+
identifier: .email
166+
blueprint: '"_user"'
167+
relations:
168+
gitlabUser: .username
169+
// highlight-end
170+
```
171+
172+
</details>
173+
174+
4. Click on `Save & Resync` to apply the changes
175+
176+
</TabItem>
177+
178+
<TabItem value="azuredevops" label="Azure DevOps">
179+
180+
To update the Azure DevOps integration mapping, follow the steps below:
181+
182+
1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page.
183+
184+
2. Find your Azure DevOps integration and click on it.
185+
186+
3. In the mapping configuration, add a new mapping for Port User entities to establish the relation with Azure DevOps users:
187+
188+
<details>
189+
<summary><b>Updated Azure DevOps integration mapping (Click to expand)</b></summary>
190+
191+
```yaml showLineNumbers
192+
# Keep existing azureDevopsMember mapping
193+
- kind: user
194+
selector:
195+
query: 'true'
196+
port:
197+
entity:
198+
mappings:
199+
identifier: .id
200+
title: .user.displayName
201+
blueprint: '"azureDevopsMember"'
202+
properties:
203+
url: .user.url
204+
email: .user.mailAddress
205+
206+
# Add new mapping for Port Users with relation to Azure DevOps users
207+
// highlight-start
208+
- kind: user
209+
selector:
210+
query: '.user.mailAddress != null'
211+
port:
212+
entity:
213+
mappings:
214+
identifier: .user.mailAddress
215+
blueprint: '"_user"'
216+
relations:
217+
azureDevopsUser: .id
218+
// highlight-end
219+
```
220+
221+
</details>
222+
223+
4. Click on `Save & Resync` to apply the changes.
224+
225+
</TabItem>
226+
227+
</Tabs>
228+
229+
## Set up automation
230+
231+
To ensure new Port users are automatically mapped to their corresponding Git user accounts when a new Port user is created, we'll create an automation that triggers when a new Port user is created.
232+
233+
1. Go to the [Automations](https://app.getport.io/settings/automations) page of your portal.
234+
235+
2. Click on `+ Automation`.
236+
237+
3. Click on the `Edit JSON` button in the top right corner.
238+
239+
4. Copy and paste the following automation configuration:
240+
241+
<details>
242+
<summary><b>Automation to sync Port users to Git user accounts (Click to expand)</b></summary>
243+
244+
```json showLineNumbers
245+
{
246+
"identifier": "sync_port_user_for_git_users",
247+
"title": "Sync Port User for Git Users",
248+
"description": "Automatically maps Port users to their corresponding Git user accounts across all platforms",
249+
"icon": "Git",
250+
"trigger": {
251+
"type": "automation",
252+
"event": {
253+
"type": "ENTITY_CREATED",
254+
"blueprintIdentifier": "_user"
255+
},
256+
"condition": {
257+
"type": "JQ",
258+
"expressions": [],
259+
"combinator": "and"
260+
}
261+
},
262+
"invocationMethod": {
263+
"type": "WEBHOOK",
264+
"url": "https://api.getport.io/v1/entities/_user/{{ .event.diff.after.identifier }}/relations",
265+
"agent": false,
266+
"synchronized": true,
267+
"method": "POST",
268+
"headers": {
269+
"Content-Type": "application/json"
270+
},
271+
"body": {
272+
"relations": {
273+
"githubUser": {
274+
"combinator": "and",
275+
"rules": [
276+
{
277+
"property": "$identifier",
278+
"operator": "=",
279+
"value": "{{ .event.diff.after.identifier }}"
280+
}
281+
]
282+
},
283+
"gitlabUser": {
284+
"combinator": "and",
285+
"rules": [
286+
{
287+
"property": "$identifier",
288+
"operator": "=",
289+
"value": "{{ .event.diff.after.identifier }}"
290+
}
291+
]
292+
},
293+
"azureDevopsUser": {
294+
"combinator": "and",
295+
"rules": [
296+
{
297+
"property": "$identifier",
298+
"operator": "=",
299+
"value": "{{ .event.diff.after.identifier }}"
300+
}
301+
]
302+
}
303+
}
304+
}
305+
},
306+
"publish": true
307+
}
308+
```
309+
310+
:::tip Select the relevant Git integration
311+
In this automation example, we show how to map Port users to all supported Git platforms (GitHub, GitLab, and Azure DevOps) at once. In practice, you should only configure the relation for the Git platform your organization actually uses. For example, if your users are only in GitHub, include the `githubUser` relation and remove the others. Adjust the configuration to match your organization's setup.
312+
:::
313+
314+
</details>
315+
316+
5. Click `Save` to create the automation.
317+
318+
## Let's test it!
319+
320+
1. Go to your [Software catalog](https://app.getport.io/catalog) page
321+
322+
2. Search for a Git user entity (e.g., `GitHub User`, `GitLab User`, or `Azure DevOps User`)
323+
324+
3. Verify that the user has a relationship with the corresponding Port user account.
325+
326+
4. Check that the relationship is established automatically for new Git users.
327+

‎docs/guides/all/map-jira-users-to-port-accounts.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,11 @@ This guide assumes the following:
2424

2525
The relation between Jira users and Port users is created automatically when we install the [Jira integration](/build-your-software-catalog/sync-data-to-catalog/project-management/jira/). If you haven't installed it yet, please do so first.
2626

27-
<h3>Add mirror properties to the Port User blueprint</h3>
27+
<h3>Optional: Add mirror properties to the Port User blueprint</h3>
28+
29+
If you want to display some Jira user attributes e.g. display name, account type, time zone, etc. in the Port User blueprint, you can add a mirror property to the Port User blueprint.
30+
31+
Follow the steps below to add a mirror property to the Port User blueprint:
2832

2933
1. Go to the [data model](https://app.getport.io/settings/data-model) page of your portal.
3034

‎src/components/guides-section/consts.js‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1336,6 +1336,13 @@ export const availableGuides = [
13361336
logos: ["GitHub"],
13371337
link: "/guides/all/visualize-and-manage-github-deployments",
13381338
},
1339+
{
1340+
title: "Map Git users to Port user accounts",
1341+
description: "Automatically map Git users to their Port user accounts for seamless integration",
1342+
tags: ["SDLC","Git", "GitHub", "GitLab", "AzureDevops", "Automations"],
1343+
logos: ["Git"],
1344+
link: "/guides/all/map-git-users-to-port-accounts",
1345+
},
13391346
{
13401347
title: "Ingest and map HiBob users to Port user accounts",
13411348
description: "Ingest and map HiBob users to Port user accounts for seamless integration",
@@ -1351,16 +1358,13 @@ export const availableGuides = [
13511358
link: "/guides/all/map-jira-users-to-port-accounts",
13521359
},
13531360
{
1354-
1355-
13561361
title: "Ingest and map Slack users to Port user accounts",
13571362
description: "Ingest and map Slack users to Port user accounts for seamless integration",
13581363
tags: ["SDLC", "Slack", "Actions", "Automations","Webhook"],
13591364
logos: ["Slack", "Webhook"],
13601365
link: "/guides/all/map-slack-users-to-port-accounts",
13611366
},
13621367
{
1363-
13641368
title: "Ingest and map ServiceNow users to Port user accounts",
13651369
description: "Ingest and map ServiceNow users to Port user accounts for seamless integration",
13661370
tags: ["SDLC", "ServiceNow", "Actions", "Automations", "Webhook"],
@@ -1402,7 +1406,6 @@ export const availableGuides = [
14021406
logos: ["AI", "GitHub"],
14031407
link: "/guides/all/self-heal-scorecards-with-ai",
14041408
}
1405-
14061409
]
14071410

14081411
// Enhance guides with metadata (isNew property)

0 commit comments

Comments
 (0)