From 1c21e6fa0be259050d4805e054a684c71c4862e9 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Wed, 29 Oct 2025 18:27:02 +0200 Subject: [PATCH 1/5] WIP --- ...lab_integration_example_package_config.mdx | 23 ++++++++++++++++++- .../git/gitlab-v2/examples.md | 5 ++-- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx index 86a0a40188..87fe1344f7 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx @@ -1,6 +1,6 @@
Integration mapping (click to expand) -```yaml showLineNumbers +```yaml showLineNumbers title="Integration mapping JSON file" resources: - kind: file selector: @@ -23,4 +23,25 @@ resources: package: .item.key version: .item.value ``` + +```yaml showLineNumbers title="Integration mapping YAML file" +resources: + - kind: file + selector: + query: 'true' + files: + path: config.yml + repos: + - getport-labs/my-project + port: + entity: + mappings: + # Note that when parsing a YAML file, you should specify the index the parsed document. + identifier: .file.content.[0].identifier + title: .file.content.[0].title + blueprint: .file.content.[0].blueprint + properties: + slack_channel_name: .file.content.[0].properties.slack_channel_name + description: .file.content.[0].properties.description +```
\ No newline at end of file diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md index 7477810118..06581971e8 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md @@ -164,8 +164,9 @@ You can use the following Port blueprint definitions and integration configurati -The example will parse the `package.json` file in your repository and extract the dependencies into Port entities. -For more information about ingesting files and file contents, click [here](/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/#ingest-files-from-your-repositories) +The integration mapping example above demonstrates both a JSON file (`package.json`) and a YAML file (`config.yml`) configuration. +The example will parse the file in your repository and extract the dependencies into Port entities. +For more information about ingesting files and file contents, click [here](/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/#ingest-files-from-your-repositories). From fa7492f1023f86a5959d8e65e1b25ddf2afa3854 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Thu, 30 Oct 2025 09:57:59 +0200 Subject: [PATCH 2/5] WIP --- ...lab_integration_example_package_config.mdx | 37 ++++++++++++++----- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx index 87fe1344f7..727aa93afe 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx @@ -1,5 +1,15 @@ +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +
Integration mapping (click to expand) + + + + ```yaml showLineNumbers title="Integration mapping JSON file" resources: - kind: file @@ -11,7 +21,7 @@ resources: # Replace with your repository's path_with_namespace (e.g., "group/project" or "group/subgroup/project") - group/my-project port: - itemsToParse: .file.content.dependencies | to_entries + itemsToParse: .file.content.dependencies | to_entries entity: mappings: identifier: >- @@ -23,7 +33,8 @@ resources: package: .item.key version: .item.value ``` - + + ```yaml showLineNumbers title="Integration mapping YAML file" resources: - kind: file @@ -32,16 +43,24 @@ resources: files: path: config.yml repos: - - getport-labs/my-project + # Replace with your repository's path_with_namespace (e.g., "group/project" or "group/subgroup/project") + - group/my-project port: + # Note that when parsing a YAML file, you should specify the index the parsed document. + # highlight-start + itemsToParse: .file.content.[0].dependencies | to_entries + # highlight-end entity: mappings: - # Note that when parsing a YAML file, you should specify the index the parsed document. - identifier: .file.content.[0].identifier - title: .file.content.[0].title - blueprint: .file.content.[0].blueprint + identifier: >- + .item.key + "_" + if (.item.value | startswith("^")) then + .item.value[1:] else .item.value end + title: .item.key + "@" + .item.value + blueprint: '"package"' properties: - slack_channel_name: .file.content.[0].properties.slack_channel_name - description: .file.content.[0].properties.description + package: .item.key + version: .item.value ``` + +
\ No newline at end of file From 9e3d79a94dcb6403e5d81ff7f40e6454e91306b2 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Thu, 30 Oct 2025 15:35:36 +0200 Subject: [PATCH 3/5] update the docs with the new example and remove the mapping word from the headers --- ...lab_integration_example_package_config.mdx | 44 +--------------- ...lab_integration_example_team_blueprint.mdx | 29 +++++++++++ ...gration_example_team_yaml_file_example.mdx | 11 ++++ ...gitlab_integration_example_yaml_config.mdx | 26 ++++++++++ .../git/gitlab-v2/examples.md | 51 ++++++++++++------- 5 files changed, 102 insertions(+), 59 deletions(-) create mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_team_blueprint.mdx create mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_team_yaml_file_example.mdx create mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_yaml_config.mdx diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx index 727aa93afe..86a0a40188 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx @@ -1,16 +1,6 @@ -import Tabs from "@theme/Tabs" -import TabItem from "@theme/TabItem" -
Integration mapping (click to expand) - - - - -```yaml showLineNumbers title="Integration mapping JSON file" +```yaml showLineNumbers resources: - kind: file selector: @@ -21,7 +11,7 @@ resources: # Replace with your repository's path_with_namespace (e.g., "group/project" or "group/subgroup/project") - group/my-project port: - itemsToParse: .file.content.dependencies | to_entries + itemsToParse: .file.content.dependencies | to_entries entity: mappings: identifier: >- @@ -33,34 +23,4 @@ resources: package: .item.key version: .item.value ``` - - -```yaml showLineNumbers title="Integration mapping YAML file" -resources: - - kind: file - selector: - query: 'true' - files: - path: config.yml - repos: - # Replace with your repository's path_with_namespace (e.g., "group/project" or "group/subgroup/project") - - group/my-project - port: - # Note that when parsing a YAML file, you should specify the index the parsed document. - # highlight-start - itemsToParse: .file.content.[0].dependencies | to_entries - # highlight-end - entity: - mappings: - identifier: >- - .item.key + "_" + if (.item.value | startswith("^")) then - .item.value[1:] else .item.value end - title: .item.key + "@" + .item.value - blueprint: '"package"' - properties: - package: .item.key - version: .item.value -``` - -
\ No newline at end of file diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_team_blueprint.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_team_blueprint.mdx new file mode 100644 index 0000000000..e8501cdf14 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_team_blueprint.mdx @@ -0,0 +1,29 @@ +
+Team blueprint (click to expand) +```json showLineNumbers +{ + "identifier": "team", + "title": "team", + "icon": "Team", + "schema": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "slack_channel_name": { + "type": "string", + "title": "Slack channel name" + } + }, + "required": [ + "description" + ] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} +} +``` +
\ No newline at end of file diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_team_yaml_file_example.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_team_yaml_file_example.mdx new file mode 100644 index 0000000000..db0d203cef --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_team_yaml_file_example.mdx @@ -0,0 +1,11 @@ +
+YAML file example (click to expand) +```yaml showLineNumbers +blueprint: team +identifier: team +title: development_team +properties: + description: Development team + slack_channel_name: development-team +``` +
\ No newline at end of file diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_yaml_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_yaml_config.mdx new file mode 100644 index 0000000000..c210629026 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_yaml_config.mdx @@ -0,0 +1,26 @@ +
+Integration mapping (click to expand) +```yaml showLineNumbers +resources: + - kind: file + selector: + query: 'true' + files: + path: teams_file.yml + repos: + # Replace with your repository's path_with_namespace (e.g., "group/project" or "group/subgroup/project") + - getport-labs/my-project + port: + entity: + mappings: + # Note that when parsing a YAML file, you should specify the index of the parsed document event when there is only one document. + #highlight-start + identifier: .file.content.[0].identifier + title: .file.content.[0].title + blueprint: .file.content.[0].blueprint + properties: + slack_channel_name: .file.content.[0].properties.slack_channel_name + description: .file.content.[0].properties.description + #highlight-end +``` +
\ No newline at end of file diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md index 06581971e8..3132582d0e 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md @@ -28,13 +28,18 @@ import ReleaseBlueprint from './example-releases/_gitlab_integration_example_rel import ReleaseConfig from './example-releases/_gitlab_integration_example_release_config.mdx' import TagBlueprint from './example-tags/_gitlab_integration_example_tag_blueprint.mdx' import TagConfig from './example-tags/_gitlab_integration_example_tag_config.mdx' +import TeamBlueprint from './example-files/_gitlab_integration_example_team_blueprint.mdx' +import YamlConfig from './example-files/_gitlab_integration_example_yaml_config.mdx' +import TeamsYamlFileExample from './example-files/_gitlab_integration_example_team_yaml_file_example.mdx' import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" # Examples -## Mapping groups +## Mapping examples + +### Groups The following example demonstrates how to ingest your GitLab groups, subgroups and projects to Port. You can use the following Port blueprint definitions and integration configuration: @@ -56,7 +61,7 @@ You can use the following Port blueprint definitions and integration configurati -## Mapping projects, README.md and merge requests +### Projects, README.md and merge requests :::caution Merge request access requirement Merge requests are fetched at the **group level**. Ensure your integration token has access to the parent GitLab group that contains your projects. Project-level access alone is not sufficient for merge request visibility. @@ -75,7 +80,7 @@ You can use the following Port blueprint definitions and integration configurati -### Merge request configuration options +#### Merge request configuration options @@ -133,7 +138,7 @@ By default, if not specified, it is set to `90` days. -## Mapping projects and issues +### Projects and issues The following example demonstrates how to ingest your GitLab projects and their issues to Port. You can use the following Port blueprint definitions and integration configuration: @@ -155,7 +160,9 @@ You can use the following Port blueprint definitions and integration configurati -## Mapping files and file contents +### Files and file contents + +Below are two examples for mapping files and contents: The following example shows how to ingest dependencies from a `package.json` file in your GitLab repository into Port. You can use the following Port blueprint definitions and integration configuration: @@ -164,13 +171,23 @@ You can use the following Port blueprint definitions and integration configurati -The integration mapping example above demonstrates both a JSON file (`package.json`) and a YAML file (`config.yml`) configuration. -The example will parse the file in your repository and extract the dependencies into Port entities. -For more information about ingesting files and file contents, click [here](/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/#ingest-files-from-your-repositories). +The example will parse the `package.json` file in your repository and extract the dependencies into Port entities. + +___ + +The following example shows how to ingest teams from a YAML file in your GitLab repository into Port. + + + + + +The example will parse the YAML file in your repository and extract the teams into Port entities. + +For more information about ingesting files and file contents, click [here](/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/#ingest-files-from-your-repositories). -## Mapping projects and monorepos +### Projects and monorepos The following example demonstrates how to ingest your GitLab projects and their monorepo folders to Port. You can use the following Port blueprint definitions and integration configuration: @@ -219,7 +236,7 @@ You can also specify a different path for each monorepo repository, for example: -## Mapping projects and folders +### Projects and folders The following example demonstrates how to ingest your GitLab projects and their folders to Port. You can use the following Port blueprint definitions and integration configuration: @@ -248,9 +265,9 @@ resources: ``` ::: -## Mapping members and group with members +### Mapping members and group with members -### Prerequisites +#### Prerequisites - When using **GitLab Self Hosted**, an admin token is required, rather than a group access token, to retrieve the `primary email addresses` of members. - When using **GitLab Enterprise**, accounts can retrieve the `primary email addresses` of members within their groups, provided the members are part of user accounts administered by an organization with [verified domains for groups](https://docs.gitlab.com/ee/user/enterprise_user/#verified-domains-for-groups). For more information, see [limitations](https://docs.gitlab.com/ee/api/members.html#limitations). @@ -259,7 +276,7 @@ resources: Primary email addresses are not available for GitLab "Free plan" users. ::: -### Mapping members +#### Mapping members The following example demonstrates how to ingest your GitLab members to Port. You can use the following Port blueprint definitions and integration configuration: @@ -270,7 +287,7 @@ You can use the following Port blueprint definitions and integration configurati -### Mapping groups with members +#### Mapping groups with members The following example demonstrates how to ingest your GitLab groups and their members to Port. You can use the following Port blueprint definitions and integration configuration: @@ -315,7 +332,7 @@ By default, this selector is set to `false`, which means the integration will on ::: -## Mapping projects, pipelines and jobs +### Projects, pipelines and jobs The following example demonstrates how to ingest your GitLab projects, their pipelines and jobs runs to Port. You can use the following Port blueprint definitions and integration configuration: @@ -336,7 +353,7 @@ You can use the following Port blueprint definitions and integration configurati ::: -## Mapping releases +### Releases The following example demonstrates how to ingest your GitLab releases to Port. You can use the following Port blueprint definitions and integration configuration: @@ -353,7 +370,7 @@ You can use the following Port blueprint definitions and integration configurati ::: -## Mapping tags +## Tags The following example demonstrates how to ingest your GitLab tags to Port. You can use the following Port blueprint definitions and integration configuration: From 6424b5c705aeb3547fd0cb858ad8908ab6b93113 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Thu, 30 Oct 2025 15:43:00 +0200 Subject: [PATCH 4/5] change the order of the collapsibles --- .../sync-data-to-catalog/git/gitlab-v2/examples.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md index 3132582d0e..2262e626e7 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md @@ -179,10 +179,10 @@ The following example shows how to ingest teams from a YAML file in your GitLab - - + + The example will parse the YAML file in your repository and extract the teams into Port entities. For more information about ingesting files and file contents, click [here](/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/#ingest-files-from-your-repositories). From 8e81e3df8c80a266c36341a0ffbfc6a1100e678a Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Thu, 30 Oct 2025 15:54:58 +0200 Subject: [PATCH 5/5] change tag to be under mapping examples --- .../sync-data-to-catalog/git/gitlab-v2/examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md index 2262e626e7..9ea43938ef 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/examples.md @@ -370,7 +370,7 @@ You can use the following Port blueprint definitions and integration configurati ::: -## Tags +### Tags The following example demonstrates how to ingest your GitLab tags to Port. You can use the following Port blueprint definitions and integration configuration: