From 94ae2bc485dd7c57c7248ec776dbe155a5637e51 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Thu, 24 Jul 2025 03:43:52 +0000 Subject: [PATCH 1/6] Add new guide for mapping Git users to Port accounts --- .../all/map-git-users-to-port-accounts.md | 391 ++++++++++++++++++ src/components/guides-section/consts.js | 7 + 2 files changed, 398 insertions(+) create mode 100644 docs/guides/all/map-git-users-to-port-accounts.md diff --git a/docs/guides/all/map-git-users-to-port-accounts.md b/docs/guides/all/map-git-users-to-port-accounts.md new file mode 100644 index 0000000000..2c5fcb9c29 --- /dev/null +++ b/docs/guides/all/map-git-users-to-port-accounts.md @@ -0,0 +1,391 @@ +--- +displayed_sidebar: null +description: Automatically map GitHub, GitLab, and Azure DevOps users to their Port user accounts for seamless integration +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Map Git users to Port user accounts + +This guide demonstrates how to automatically map Git users to existing Port user accounts based on email addresses. + +Once implemented, users will be able to: +- Maintain a complete inventory of all Git users in your organization within Port +- Automatically link Git users to their corresponding Port user accounts for seamless integration +- Provide visibility into which Git users have Port accounts and which don't + +## Prerequisites + +This guide assumes the following: +- You have a Port account and have completed the [onboarding process](https://docs.port.io/getting-started/overview). +- You have the relevant Git integration installed and configured: + - [Port's GitHub App](/build-your-software-catalog/sync-data-to-catalog/git/github-exporter/). + - [Port's GitLab integration](/build-your-software-catalog/sync-data-to-catalog/git/gitlab-exporter/). + - [Port's Azure DevOps integration](/build-your-software-catalog/sync-data-to-catalog/git/azure-devops-exporter/). +- You have permissions to create automations in Port. + +## Set up data model + +To establish relationships between Git users and Port user accounts, we need to add a relation to the existing Git user blueprints. + +

Update the Git user blueprints

+ +1. Go to the [data model](https://app.getport.io/settings/data-model) page of your portal. + +2. Find the relevant Git user blueprint (`GitHub User`, `GitLab User`, or `Azure DevOps User`) and click on it. + +3. Click on the `Edit JSON` button in the top right corner. + +4. Add the following relation to the `relations` section: + + ```json showLineNumbers + "user": { + "title": "Port User", + "target": "_user", + "required": false, + "many": false + } + ``` + +5. Click on `Save` to update the blueprint. + +## Implementation + +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. + + + + +

Update the GitHub integration mapping

+ +To update the GitHub integration mapping, follow the steps below: + +1. Go to the [data sources](https://app.getport.io/settings/data-sources) page. + +2. Find your GitHub integration and click on it. + +3. In the mapping configuration, update the user mapping to include the relation: + +
+ GitHub integration mapping (Click to expand) + + ```yaml showLineNumbers + - kind: user + selector: + query: 'true' + port: + entity: + mappings: + identifier: .login + title: .login + blueprint: '"githubUser"' + properties: + email: .email + relations: + user: + combinator: '"and"' + rules: + - property: '"$identifier"' + operator: '"="' + value: .email + ``` + +
+ +4. Click on `Save & Resync` to apply the changes + +

Create automation to sync GitHub users when a new Port user is added

+ +To ensure new Port users get mapped to GitHub users automatically, we'll create an automation that triggers when a new Port user is created. + +Follow the steps below to create the automation: + +1. Go to the [automations](https://app.getport.io/settings/automations) page of your portal. + +2. Click on `+ Automation`. + +3. Click on the `Edit JSON` button in the top right corner. + +4. Copy and paste the following automation configuration: + +
+ Automation to sync GitHub users when a new Port user is added (Click to expand) + + ```json showLineNumbers + { + "identifier": "sync_github_user_for_new_port_user", + "title": "Sync GitHub User for New Port User", + "description": "Automatically maps GitHub users to newly created Port user accounts", + "icon": "GitHub", + "trigger": { + "type": "automation", + "event": { + "type": "ENTITY_CREATED", + "blueprintIdentifier": "_user" + }, + "condition": { + "type": "JQ", + "expressions": [], + "combinator": "and" + } + }, + "invocationMethod": { + "type": "WEBHOOK", + "url": "https://api.getport.io/v1/entities/gitHubUser/{{ .event.diff.after.identifier }}/relations", + "agent": false, + "synchronized": true, + "method": "POST", + "headers": { + "Content-Type": "application/json" + }, + "body": { + "relations": { + "user": { + "identifier": "{{ .event.diff.after.identifier }}" + } + } + } + }, + "publish": true + } + ``` + +
+ +5. Click `Save` to create the automation + + + + + +

Update the GitLab integration mapping

+ +To update the GitLab integration mapping, follow the steps below: + +1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page. + +2. Find your GitLab integration and click on it. + +3. In the mapping configuration, update the user mapping to include the relation: + +
+ GitLab integration mapping (Click to expand) + + ```yaml showLineNumbers + - kind: member + selector: + query: 'true' + port: + entity: + mappings: + identifier: .username + title: .name + blueprint: '"gitlabMember"' + properties: + url: .web_url + state: .state + email: .email + locked: .locked + // highlight-start + relations: + user: + combinator: '"and"' + rules: + - property: "$identifier" + operator: '"="' + value: .email + // highlight-end + ``` + +
+ +4. Click on `Save & Resync` to apply the changes + +

Create automation to sync GitLab users when a new Port user is added

+ +To ensure new Port users get mapped to GitLab users automatically, we'll create an automation that triggers when a new Port user is created. + +Follow the steps below to create the automation: + +1. Go to the [automations](https://app.getport.io/settings/automations) page of your portal. + +2. Click on `+ Automation`. + +3. Click on the `Edit JSON` button in the top right corner. + +4. Copy and paste the following automation configuration: + +
+ Automation to sync GitLab users when a new Port user is added (Click to expand) + + ```json showLineNumbers + { + "identifier": "sync_gitlab_user_for_new_port_user", + "title": "Sync GitLab User for New Port User", + "description": "Automatically maps GitLab users to newly created Port user accounts", + "icon": "GitLab", + "trigger": { + "type": "automation", + "event": { + "type": "ENTITY_CREATED", + "blueprintIdentifier": "_user" + }, + "condition": { + "type": "JQ", + "expressions": [], + "combinator": "and" + } + }, + "invocationMethod": { + "type": "WEBHOOK", + "url": "https://api.getport.io/v1/entities/gitLabUser/{{ .event.diff.after.identifier }}/relations", + "agent": false, + "synchronized": true, + "method": "POST", + "headers": { + "Content-Type": "application/json" + }, + "body": { + "relations": { + "user": { + "identifier": "{{ .event.diff.after.identifier }}" + } + } + } + }, + "publish": true + } + ``` + +
+ +5. Click `Save` to create the automation + + + + + +

Update the Azure DevOps integration mapping

+ +To update the Azure DevOps integration mapping, follow the steps below: + +1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page. + +2. Find your Azure DevOps integration and click on it. + +3. In the mapping configuration, update the user mapping to include the relation: + +
+ Azure DevOps integration mapping (Click to expand) + + ```yaml showLineNumbers + - kind: user + selector: + query: 'true' + port: + entity: + mappings: + identifier: .id + title: .user.displayName + blueprint: '"azureDevopsMember"' + properties: + url: .user.url + email: .user.mailAddress + // highlight-start + relations: + user: + combinator: '"and"' + rules: + - property: "$identifier" + operator: '"="' + value: .user.mailAddress + // highlight-end + ``` + +
+ +4. Click on `Save & Resync` to apply the changes. + +

Create automation to sync Azure DevOps users when a new Port user is added

+ +To ensure new Port users get mapped to Azure DevOps users automatically, we'll create an automation that triggers when a new Port user is created. + +Follow the steps below to create the automation: + +1. Go to the [automations](https://app.getport.io/settings/automations) page of your portal. + +2. Click on `+ Automation`. + +3. Click on the `Edit JSON` button in the top right corner. + +4. Copy and paste the following automation configuration: + +
+ Automation to sync Azure DevOps users when a new Port user is added (Click to expand) + + ```json showLineNumbers + { + "identifier": "sync_azuredevops_user_for_new_port_user", + "title": "Sync Azure DevOps User for New Port User", + "description": "Automatically maps Azure DevOps users to newly created Port user accounts", + "icon": "AzureDevops", + "trigger": { + "type": "automation", + "event": { + "type": "ENTITY_CREATED", + "blueprintIdentifier": "_user" + }, + "condition": { + "type": "JQ", + "expressions": [], + "combinator": "and" + } + }, + "invocationMethod": { + "type": "WEBHOOK", + "url": "https://api.getport.io/v1/entities/azureDevopsUser/{{ .event.diff.after.identifier }}/relations", + "agent": false, + "synchronized": true, + "method": "POST", + "headers": { + "Content-Type": "application/json", + }, + "body": { + "relations": { + "user": { + "identifier": "{{ .event.diff.after.identifier }}" + } + } + } + }, + "publish": true + } + ``` + +
+ +5. Click `Save` to create the automation. + + + + + +:::tip Mapping explanation +These configurations automatically establish relationships between Git users and Port user accounts by matching the Git user's email address with the Port user's identifier (which is typically the email address). +::: + +## Let's test it! + +1. Go to your [software catalog](https://app.getport.io/catalog) page + +2. Search for a Git user entity (e.g., `GitHub User`, `GitLab User`, or `Azure DevOps User`) + +3. Verify that the user has a relationship with the corresponding Port user account. + +4. Check that the relationship is established automatically for new Git users. + + +## Conclusion + +You've successfully set up automatic mapping between Git users and Port user accounts. + diff --git a/src/components/guides-section/consts.js b/src/components/guides-section/consts.js index b961af6a40..f4093fa64b 100644 --- a/src/components/guides-section/consts.js +++ b/src/components/guides-section/consts.js @@ -1339,5 +1339,12 @@ export const availableGuides = [ logos: ["GitHub"], link: "/guides/all/visualize-and-manage-github-deployments", }, + { + title: "Map Git users to Port user accounts", + description: "Automatically map Git users to their Port user accounts for seamless integration", + tags: ["SDLC","Git", "GitHub", "GitLab", "AzureDevops", "Automations"], + logos: ["Git"], + link: "/guides/all/map-git-users-to-port-accounts", + }, ] From 7c2e5fbdbb4b68e761326c8ea933b344f2343b8e Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Thu, 24 Jul 2025 10:45:56 +0000 Subject: [PATCH 2/6] Update links and headings for consistency in the Git users to Port accounts guide --- .../all/map-git-users-to-port-accounts.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/guides/all/map-git-users-to-port-accounts.md b/docs/guides/all/map-git-users-to-port-accounts.md index 2c5fcb9c29..d78ddbcdf7 100644 --- a/docs/guides/all/map-git-users-to-port-accounts.md +++ b/docs/guides/all/map-git-users-to-port-accounts.md @@ -19,9 +19,9 @@ Once implemented, users will be able to: This guide assumes the following: - You have a Port account and have completed the [onboarding process](https://docs.port.io/getting-started/overview). - You have the relevant Git integration installed and configured: - - [Port's GitHub App](/build-your-software-catalog/sync-data-to-catalog/git/github-exporter/). - - [Port's GitLab integration](/build-your-software-catalog/sync-data-to-catalog/git/gitlab-exporter/). - - [Port's Azure DevOps integration](/build-your-software-catalog/sync-data-to-catalog/git/azure-devops-exporter/). + - [Port's GitHub Integrtion](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/). + - [Port's GitLab integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/). + - [Port's Azure DevOps integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/). - You have permissions to create automations in Port. ## Set up data model @@ -30,7 +30,7 @@ To establish relationships between Git users and Port user accounts, we need to

Update the Git user blueprints

-1. Go to the [data model](https://app.getport.io/settings/data-model) page of your portal. +1. Go to the [Data model](https://app.getport.io/settings/data-model) page of your portal. 2. Find the relevant Git user blueprint (`GitHub User`, `GitLab User`, or `Azure DevOps User`) and click on it. @@ -60,7 +60,7 @@ Now we'll update the integration mapping to include the relation and create auto To update the GitHub integration mapping, follow the steps below: -1. Go to the [data sources](https://app.getport.io/settings/data-sources) page. +1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page. 2. Find your GitHub integration and click on it. @@ -100,7 +100,7 @@ To ensure new Port users get mapped to GitHub users automatically, we'll create Follow the steps below to create the automation: -1. Go to the [automations](https://app.getport.io/settings/automations) page of your portal. +1. Go to the [Automations](https://app.getport.io/settings/automations) page of your portal. 2. Click on `+ Automation`. @@ -207,7 +207,7 @@ To ensure new Port users get mapped to GitLab users automatically, we'll create Follow the steps below to create the automation: -1. Go to the [automations](https://app.getport.io/settings/automations) page of your portal. +1. Go to the [Automations](https://app.getport.io/settings/automations) page of your portal. 2. Click on `+ Automation`. @@ -312,7 +312,7 @@ To ensure new Port users get mapped to Azure DevOps users automatically, we'll c Follow the steps below to create the automation: -1. Go to the [automations](https://app.getport.io/settings/automations) page of your portal. +1. Go to the [Automations](https://app.getport.io/settings/automations) page of your portal. 2. Click on `+ Automation`. @@ -376,7 +376,7 @@ These configurations automatically establish relationships between Git users and ## Let's test it! -1. Go to your [software catalog](https://app.getport.io/catalog) page +1. Go to your [Software catalog](https://app.getport.io/catalog) page 2. Search for a Git user entity (e.g., `GitHub User`, `GitLab User`, or `Azure DevOps User`) From d47e1e10c8a70fff481e1f3cb1ab83ae783092cd Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Thu, 31 Jul 2025 15:17:45 +0000 Subject: [PATCH 3/6] Enhance documentation for mapping Git users to Port accounts by updating the Port User blueprint and integration mappings for GitHub, GitLab, and Azure DevOps. Added detailed instructions for establishing relations and mirror properties, along with automation setup for syncing users across platforms. --- .../all/map-git-users-to-port-accounts.md | 389 ++++++++---------- 1 file changed, 180 insertions(+), 209 deletions(-) diff --git a/docs/guides/all/map-git-users-to-port-accounts.md b/docs/guides/all/map-git-users-to-port-accounts.md index d78ddbcdf7..dc3f5e73ac 100644 --- a/docs/guides/all/map-git-users-to-port-accounts.md +++ b/docs/guides/all/map-git-users-to-port-accounts.md @@ -26,28 +26,77 @@ This guide assumes the following: ## Set up data model -To establish relationships between Git users and Port user accounts, we need to add a relation to the existing Git user blueprints. +To establish relationships between Git users and Port user accounts, we need to enhance the Port User blueprint to add relations to the Git user blueprints. -

Update the Git user blueprints

+

Enhance the Port User blueprint

-1. Go to the [Data model](https://app.getport.io/settings/data-model) page of your portal. +Now we need to enhance the Port User blueprint to add relations to the Git user blueprints and mirror properties to display Git information. -2. Find the relevant Git user blueprint (`GitHub User`, `GitLab User`, or `Azure DevOps User`) and click on it. +1. Go to the [data model](https://app.getport.io/settings/data-model) page of your portal. + +2. Find the `User` blueprint and click on it. 3. Click on the `Edit JSON` button in the top right corner. -4. Add the following relation to the `relations` section: +4. Add the following relations to the `relations` object (add only the ones relevant to your Git integrations): + +
+ Port User blueprint relations (Click to expand) ```json showLineNumbers - "user": { - "title": "Port User", - "target": "_user", + "relations": { + "githubUser": { + "title": "GitHub User", + "target": "githubUser", + "required": false, + "many": false + }, + "gitlabUser": { + "title": "GitLab User", + "target": "gitlabMember", + "required": false, + "many": false + }, + "azureDevopsUser": { + "title": "Azure DevOps User", + "target": "azureDevopsMember", "required": false, "many": false + } + } + ``` + +
+ +5. Add mirror properties to display Git user information: + +
+ Port User blueprint mirror properties (Click to expand) + + ```json showLineNumbers + "mirrorProperties": { + "github_login": { + "title": "GitHub login", + "path": "githubUser.login" + }, + "gitlab_username": { + "title": "GitLab username", + "path": "gitlabUser.username" + }, + "azuredevops_display_name": { + "title": "Azure DevOps display name", + "path": "azureDevopsUser.displayName" + } } ``` -5. Click on `Save` to update the blueprint. +
+ +6. Click on `Save` to update the blueprint. + +:::info Additional mirror properties +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. +::: ## Implementation @@ -56,259 +105,157 @@ Now we'll update the integration mapping to include the relation and create auto -

Update the GitHub integration mapping

- To update the GitHub integration mapping, follow the steps below: 1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page. 2. Find your GitHub integration and click on it. -3. In the mapping configuration, update the user mapping to include the relation: +3. In the mapping configuration, add a new mapping for Port User entities to establish the relation with GitHub users:
- GitHub integration mapping (Click to expand) + Updated GitHub integration mapping (Click to expand) ```yaml showLineNumbers + # Keep existing githubUser mapping - kind: user - selector: + selector: query: 'true' - port: + port: entity: - mappings: + mappings: identifier: .login title: .login blueprint: '"githubUser"' properties: - email: .email + email: .email + + # Add new mapping for Port Users with relation to GitHub users + // highlight-start + - kind: user + selector: + query: '.email != null' + port: + entity: + mappings: + identifier: .email + blueprint: '"_user"' relations: - user: - combinator: '"and"' - rules: - - property: '"$identifier"' - operator: '"="' - value: .email + githubUser: .login + // highlight-end ```
4. Click on `Save & Resync` to apply the changes -

Create automation to sync GitHub users when a new Port user is added

- -To ensure new Port users get mapped to GitHub users automatically, we'll create an automation that triggers when a new Port user is created. - -Follow the steps below to create the automation: - -1. Go to the [Automations](https://app.getport.io/settings/automations) page of your portal. - -2. Click on `+ Automation`. - -3. Click on the `Edit JSON` button in the top right corner. - -4. Copy and paste the following automation configuration: - -
- Automation to sync GitHub users when a new Port user is added (Click to expand) - - ```json showLineNumbers - { - "identifier": "sync_github_user_for_new_port_user", - "title": "Sync GitHub User for New Port User", - "description": "Automatically maps GitHub users to newly created Port user accounts", - "icon": "GitHub", - "trigger": { - "type": "automation", - "event": { - "type": "ENTITY_CREATED", - "blueprintIdentifier": "_user" - }, - "condition": { - "type": "JQ", - "expressions": [], - "combinator": "and" - } - }, - "invocationMethod": { - "type": "WEBHOOK", - "url": "https://api.getport.io/v1/entities/gitHubUser/{{ .event.diff.after.identifier }}/relations", - "agent": false, - "synchronized": true, - "method": "POST", - "headers": { - "Content-Type": "application/json" - }, - "body": { - "relations": { - "user": { - "identifier": "{{ .event.diff.after.identifier }}" - } - } - } - }, - "publish": true - } - ``` - -
- -5. Click `Save` to create the automation - -

Update the GitLab integration mapping

- To update the GitLab integration mapping, follow the steps below: 1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page. 2. Find your GitLab integration and click on it. -3. In the mapping configuration, update the user mapping to include the relation: +3. In the mapping configuration, add a new mapping for Port User entities to establish the relation with GitLab users:
- GitLab integration mapping (Click to expand) + Updated GitLab integration mapping (Click to expand) ```yaml showLineNumbers + # Keep existing gitlabMember mapping - kind: member - selector: + selector: query: 'true' - port: + port: entity: - mappings: + mappings: identifier: .username title: .name blueprint: '"gitlabMember"' properties: - url: .web_url - state: .state - email: .email - locked: .locked - // highlight-start + url: .web_url + state: .state + email: .email + locked: .locked + + # Add new mapping for Port Users with relation to GitLab users + // highlight-start + - kind: member + selector: + query: '.email != null' + port: + entity: + mappings: + identifier: .email + blueprint: '"_user"' relations: - user: - combinator: '"and"' - rules: - - property: "$identifier" - operator: '"="' - value: .email - // highlight-end + gitlabUser: .username + // highlight-end ```
4. Click on `Save & Resync` to apply the changes -

Create automation to sync GitLab users when a new Port user is added

- -To ensure new Port users get mapped to GitLab users automatically, we'll create an automation that triggers when a new Port user is created. - -Follow the steps below to create the automation: - -1. Go to the [Automations](https://app.getport.io/settings/automations) page of your portal. - -2. Click on `+ Automation`. - -3. Click on the `Edit JSON` button in the top right corner. - -4. Copy and paste the following automation configuration: - -
- Automation to sync GitLab users when a new Port user is added (Click to expand) - - ```json showLineNumbers - { - "identifier": "sync_gitlab_user_for_new_port_user", - "title": "Sync GitLab User for New Port User", - "description": "Automatically maps GitLab users to newly created Port user accounts", - "icon": "GitLab", - "trigger": { - "type": "automation", - "event": { - "type": "ENTITY_CREATED", - "blueprintIdentifier": "_user" - }, - "condition": { - "type": "JQ", - "expressions": [], - "combinator": "and" - } - }, - "invocationMethod": { - "type": "WEBHOOK", - "url": "https://api.getport.io/v1/entities/gitLabUser/{{ .event.diff.after.identifier }}/relations", - "agent": false, - "synchronized": true, - "method": "POST", - "headers": { - "Content-Type": "application/json" - }, - "body": { - "relations": { - "user": { - "identifier": "{{ .event.diff.after.identifier }}" - } - } - } - }, - "publish": true - } - ``` - -
- -5. Click `Save` to create the automation - -

Update the Azure DevOps integration mapping

- To update the Azure DevOps integration mapping, follow the steps below: 1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page. 2. Find your Azure DevOps integration and click on it. -3. In the mapping configuration, update the user mapping to include the relation: +3. In the mapping configuration, add a new mapping for Port User entities to establish the relation with Azure DevOps users:
- Azure DevOps integration mapping (Click to expand) + Updated Azure DevOps integration mapping (Click to expand) ```yaml showLineNumbers + # Keep existing azureDevopsMember mapping - kind: user - selector: + selector: query: 'true' - port: + port: entity: - mappings: + mappings: identifier: .id title: .user.displayName blueprint: '"azureDevopsMember"' properties: - url: .user.url - email: .user.mailAddress - // highlight-start + url: .user.url + email: .user.mailAddress + + # Add new mapping for Port Users with relation to Azure DevOps users + // highlight-start + - kind: user + selector: + query: '.user.mailAddress != null' + port: + entity: + mappings: + identifier: .user.mailAddress + blueprint: '"_user"' relations: - user: - combinator: '"and"' - rules: - - property: "$identifier" - operator: '"="' - value: .user.mailAddress - // highlight-end + azureDevopsUser: .id + // highlight-end ```
4. Click on `Save & Resync` to apply the changes. -

Create automation to sync Azure DevOps users when a new Port user is added

+ + + + +## Set up automation -To ensure new Port users get mapped to Azure DevOps users automatically, we'll create an automation that triggers when a new Port user is created. +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. Follow the steps below to create the automation: @@ -321,58 +268,82 @@ Follow the steps below to create the automation: 4. Copy and paste the following automation configuration:
- Automation to sync Azure DevOps users when a new Port user is added (Click to expand) + Automation to sync Port users to Git user accounts (Click to expand) ```json showLineNumbers { - "identifier": "sync_azuredevops_user_for_new_port_user", - "title": "Sync Azure DevOps User for New Port User", - "description": "Automatically maps Azure DevOps users to newly created Port user accounts", - "icon": "AzureDevops", - "trigger": { + "identifier": "sync_port_user_for_git_users", + "title": "Sync Port User for Git Users", + "description": "Automatically maps Port users to their corresponding Git user accounts across all platforms", + "icon": "Git", + "trigger": { "type": "automation", "event": { - "type": "ENTITY_CREATED", - "blueprintIdentifier": "_user" + "type": "ENTITY_CREATED", + "blueprintIdentifier": "_user" }, "condition": { - "type": "JQ", - "expressions": [], - "combinator": "and" + "type": "JQ", + "expressions": [], + "combinator": "and" } - }, - "invocationMethod": { + }, + "invocationMethod": { "type": "WEBHOOK", - "url": "https://api.getport.io/v1/entities/azureDevopsUser/{{ .event.diff.after.identifier }}/relations", + "url": "https://api.getport.io/v1/entities/_user/{{ .event.diff.after.identifier }}/relations", "agent": false, "synchronized": true, "method": "POST", "headers": { - "Content-Type": "application/json", + "Content-Type": "application/json" }, "body": { - "relations": { - "user": { - "identifier": "{{ .event.diff.after.identifier }}" + "relations": { + "githubUser": { + "combinator": "and", + "rules": [ + { + "property": "$identifier", + "operator": "=", + "value": "{{ .event.diff.after.identifier }}" + } + ] + }, + "gitlabUser": { + "combinator": "and", + "rules": [ + { + "property": "$identifier", + "operator": "=", + "value": "{{ .event.diff.after.identifier }}" + } + ] + }, + "azureDevopsUser": { + "combinator": "and", + "rules": [ + { + "property": "$identifier", + "operator": "=", + "value": "{{ .event.diff.after.identifier }}" + } + ] } + } } - } - }, - "publish": true + }, + "publish": true } ``` + :::tip Select the relevant Git integration + 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. + ::: +
5. Click `Save` to create the automation. - - - - -:::tip Mapping explanation -These configurations automatically establish relationships between Git users and Port user accounts by matching the Git user's email address with the Port user's identifier (which is typically the email address). -::: ## Let's test it! From 47c9ecf63a13c58f3bed79650b757283964d9ed2 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Tue, 5 Aug 2025 11:45:51 +0000 Subject: [PATCH 4/6] Refine documentation for mapping Git users to Port accounts by improving clarity and structure. Updated bullet points for consistency, streamlined instructions for enhancing the Port User blueprint, and removed redundant sections to enhance readability. --- .../all/map-git-users-to-port-accounts.md | 55 +++---------------- 1 file changed, 8 insertions(+), 47 deletions(-) diff --git a/docs/guides/all/map-git-users-to-port-accounts.md b/docs/guides/all/map-git-users-to-port-accounts.md index dc3f5e73ac..ff5dc19be6 100644 --- a/docs/guides/all/map-git-users-to-port-accounts.md +++ b/docs/guides/all/map-git-users-to-port-accounts.md @@ -10,9 +10,9 @@ import TabItem from '@theme/TabItem'; This guide demonstrates how to automatically map Git users to existing Port user accounts based on email addresses. Once implemented, users will be able to: -- Maintain a complete inventory of all Git users in your organization within Port -- Automatically link Git users to their corresponding Port user accounts for seamless integration -- Provide visibility into which Git users have Port accounts and which don't +- Maintain a complete inventory of all Git users in your organization within Port. +- Automatically link Git users to their corresponding Port user accounts for seamless integration. +- Provide visibility into which Git users have Port accounts and which ones do not. ## Prerequisites @@ -26,11 +26,10 @@ This guide assumes the following: ## Set up data model -To establish relationships between Git users and Port user accounts, we need to enhance the Port User blueprint to add relations to the Git user blueprints. +The relations between Git users and Port users are created automatically when we install the relevant Git integrations. +If you haven't installed them yet, please do so first. -

Enhance the Port User blueprint

- -Now we need to enhance the Port User blueprint to add relations to the Git user blueprints and mirror properties to display Git information. +

Add mirror properties to the Port User blueprint

1. Go to the [data model](https://app.getport.io/settings/data-model) page of your portal. @@ -38,37 +37,7 @@ Now we need to enhance the Port User blueprint to add relations to the Git user 3. Click on the `Edit JSON` button in the top right corner. -4. Add the following relations to the `relations` object (add only the ones relevant to your Git integrations): - -
- Port User blueprint relations (Click to expand) - - ```json showLineNumbers - "relations": { - "githubUser": { - "title": "GitHub User", - "target": "githubUser", - "required": false, - "many": false - }, - "gitlabUser": { - "title": "GitLab User", - "target": "gitlabMember", - "required": false, - "many": false - }, - "azureDevopsUser": { - "title": "Azure DevOps User", - "target": "azureDevopsMember", - "required": false, - "many": false - } - } - ``` - -
- -5. Add mirror properties to display Git user information: +4. Add the following mirror properties to the `mirrorProperties` object to display Git user information:
Port User blueprint mirror properties (Click to expand) @@ -92,7 +61,7 @@ Now we need to enhance the Port User blueprint to add relations to the Git user
-6. Click on `Save` to update the blueprint. +5. Click on `Save` to update the blueprint. :::info Additional mirror properties 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. @@ -257,8 +226,6 @@ To update the Azure DevOps integration mapping, follow the steps below: 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. -Follow the steps below to create the automation: - 1. Go to the [Automations](https://app.getport.io/settings/automations) page of your portal. 2. Click on `+ Automation`. @@ -344,7 +311,6 @@ Follow the steps below to create the automation: 5. Click `Save` to create the automation. - ## Let's test it! 1. Go to your [Software catalog](https://app.getport.io/catalog) page @@ -355,8 +321,3 @@ Follow the steps below to create the automation: 4. Check that the relationship is established automatically for new Git users. - -## Conclusion - -You've successfully set up automatic mapping between Git users and Port user accounts. - From 58c269f62293fde928299493d84e3266b60fab8b Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Tue, 5 Aug 2025 12:01:43 +0000 Subject: [PATCH 5/6] Corrected the spelling of "integration" in the GitHub integration section of the mapping Git users to Port accounts guide for consistency and clarity. --- docs/guides/all/map-git-users-to-port-accounts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/all/map-git-users-to-port-accounts.md b/docs/guides/all/map-git-users-to-port-accounts.md index ff5dc19be6..f6997d6ba3 100644 --- a/docs/guides/all/map-git-users-to-port-accounts.md +++ b/docs/guides/all/map-git-users-to-port-accounts.md @@ -19,7 +19,7 @@ Once implemented, users will be able to: This guide assumes the following: - You have a Port account and have completed the [onboarding process](https://docs.port.io/getting-started/overview). - You have the relevant Git integration installed and configured: - - [Port's GitHub Integrtion](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/). + - [Port's GitHub integrtion](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/). - [Port's GitLab integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/). - [Port's Azure DevOps integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/). - You have permissions to create automations in Port. From 34641a914476e471130d7e2e5744aa405b8c1620 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Wed, 20 Aug 2025 14:18:53 +0000 Subject: [PATCH 6/6] Update user mapping guides to clarify optional mirror properties for Port User blueprints --- docs/guides/all/map-git-users-to-port-accounts.md | 6 +++++- docs/guides/all/map-jira-users-to-port-accounts.md | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/guides/all/map-git-users-to-port-accounts.md b/docs/guides/all/map-git-users-to-port-accounts.md index f6997d6ba3..28d2801308 100644 --- a/docs/guides/all/map-git-users-to-port-accounts.md +++ b/docs/guides/all/map-git-users-to-port-accounts.md @@ -29,7 +29,11 @@ This guide assumes the following: The relations between Git users and Port users are created automatically when we install the relevant Git integrations. If you haven't installed them yet, please do so first. -

Add mirror properties to the Port User blueprint

+

Optional: Add mirror properties to the Port User blueprint

+ +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. + +Follow the steps below to add a mirror property to the Port User blueprint: 1. Go to the [data model](https://app.getport.io/settings/data-model) page of your portal. diff --git a/docs/guides/all/map-jira-users-to-port-accounts.md b/docs/guides/all/map-jira-users-to-port-accounts.md index 04aaa22a37..812a456aaf 100644 --- a/docs/guides/all/map-jira-users-to-port-accounts.md +++ b/docs/guides/all/map-jira-users-to-port-accounts.md @@ -24,7 +24,11 @@ This guide assumes the following: 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. -

Add mirror properties to the Port User blueprint

+

Optional: Add mirror properties to the Port User blueprint

+ +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. + +Follow the steps below to add a mirror property to the Port User blueprint: 1. Go to the [data model](https://app.getport.io/settings/data-model) page of your portal.