From 51495a17d77851b2419054a7863bf66618296037 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Mon, 11 Aug 2025 13:17:54 +0000 Subject: [PATCH 1/6] Add new guide: Map PR's to services in a monorepo --- .../all/map-prs-to-services-in-monorepo.md | 290 ++++++++++++++++++ src/components/guides-section/consts.js | 7 + 2 files changed, 297 insertions(+) create mode 100644 docs/guides/all/map-prs-to-services-in-monorepo.md diff --git a/docs/guides/all/map-prs-to-services-in-monorepo.md b/docs/guides/all/map-prs-to-services-in-monorepo.md new file mode 100644 index 0000000000..afdff2c424 --- /dev/null +++ b/docs/guides/all/map-prs-to-services-in-monorepo.md @@ -0,0 +1,290 @@ +--- +displayed_sidebar: null +description: Automatically map pull requests to services in a monorepo using file path analysis +--- + +# Map PR's to services in a monorepo + +## Overview +This guide will help you implement an automation in Port that automatically maps GitHub pull requests to services in your monorepo based on the files that were changed. +This functionality streamlines monorepo management by enabling teams to quickly understand which services are affected by each change without manual analysis. + +## Prerequisites + +- Complete the [onboarding process](/getting-started/overview). +- A GitHub repository with a monorepo structure containing multiple services. +- Services organized in directories with a `service.yml` file (or similar configuration file). +- Port's [GitHub App](/build-your-software-catalog/sync-data-to-catalog/git/github/github.md) installed. +- Access to GitHub API tokens for automation. + +## Set up data model + +If you haven't installed the [GitHub integration](/build-your-software-catalog/sync-data-to-catalog/git/github), you'll need to create a blueprint for GitHub pull requests in Port. +However, we highly recommend you install the GitHub integration to have the blueprint automatically set up for you. + +

Create a blueprint for GitHub pull requests

+ +1. Go to the [blueprints](https://app.getport.io/settings/blueprints) page of your portal. + +2. Click on `+ Blueprint`. + +3. Click on the `Edit JSON` button in the top right corner. + +4. Copy and paste the following JSON schema: + +
+ GitHub pull request blueprint (Click to expand) + + ```json showLineNumbers + { + "identifier": "githubPullRequest", + "title": "Pull Request", + "icon": "Github", + "schema": { + "properties": { + "creator": { + "title": "Creator", + "type": "string" + }, + "assignees": { + "title": "Assignees", + "type": "array" + }, + "reviewers": { + "title": "Reviewers", + "type": "array" + }, + "status": { + "title": "Status", + "type": "string", + "enum": ["merged", "open", "closed"], + "enumColors": { + "merged": "purple", + "open": "green", + "closed": "red" + } + }, + "closedAt": { + "title": "Closed At", + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "title": "Updated At", + "type": "string", + "format": "date-time" + }, + "mergedAt": { + "title": "Merged At", + "type": "string", + "format": "date-time" + }, + "createdAt": { + "title": "Created At", + "type": "string", + "format": "date-time" + }, + "link": { + "format": "url", + "type": "string" + }, + "leadTimeHours": { + "title": "Lead Time in hours", + "type": "number" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": { + "days_old": { + "title": "Days Old", + "icon": "DefaultProperty", + "calculation": "(now / 86400) - (.properties.createdAt | capture(\"(?\\\\d{4}-\\\\d{2}-\\\\d{2})\") | .date | strptime(\"%Y-%m-%d\") | mktime / 86400) | floor", + "type": "number" + } + }, + "relations": { + "repository": { + "title": "Repository", + "target": "githubRepository", + "required": false, + "many": false + } + } + } + ``` +
+ +5. Click "Save" to create the blueprint. + + +## Update the data source + +The first step is to configure how services are mapped from your monorepo structure. We'll use Port's file ingestion feature to automatically create service entities based on file paths. + +Follow the steps below to update the data source: + +1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page of your portal. + +2. Find the GitHub exporter and click on it. + +3. Add the following yaml to the mapping section: + +
+ Service mapping configuration (Click to expand) + + ```yaml showLineNumbers + - kind: file + selector: + query: 'true' + files: + - path: '**/service.yml' + repos: + - platform + port: + entity: + mappings: + identifier: .file.path | split("/")[:-1] | join("/") + title: .file.content.service_name + blueprint: '"service"' + ``` + +
+ + **Note**: Adjust the `path` pattern and `repos` list according to your monorepo structure. The `identifier` mapping extracts the directory path above the `service.yml` file, which becomes the service identifier. + +6. Click "Save" to create the data source. + +:::tip Service file structure +This configuration assumes each service has a `service.yml` file in its root directory. You can modify the path pattern to match your actual service configuration file (e.g., `**/package.json`, `**/docker-compose.yml`, etc.). +::: + +## Set up automations + +Now we'll create a two-step automation workflow that: +1. Fetches the files changed in a pull request +2. Updates the PR with relations to the affected services + +### Get PR files changed + +This automation triggers when a new pull request is created and fetches the list of changed files. + +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 JSON schema: + +
+ Get files changed automation (Click to expand) + + ```json showLineNumbers + { + "identifier": "get_files_changed_for_a_pr", + "title": "Get files changed for a PR", + "description": "Fetches the list of files changed in a pull request", + "trigger": { + "type": "automation", + "event": { + "type": "ENTITY_CREATED", + "blueprintIdentifier": "githubPullRequest" + }, + "condition": { + "type": "JQ", + "expressions": [], + "combinator": "and" + } + }, + "invocationMethod": { + "type": "WEBHOOK", + "url": "{{ .event.diff.after.properties.file_change_url }}", + "agent": false, + "synchronized": true, + "method": "GET", + "headers": { + "Authorization": "Bearer {{ .secrets.ANOTHER_GITHUB_TOKEN }}", + "X-GitHub-Api-Version": "2022-11-28", + "Identifier": "{{ .event.context.entityIdentifier | tostring }}" + }, + "body": {} + }, + "publish": true + } + ``` + +
+ +5. Click "Save" to create the automation. + +:::info GitHub token requirement +This automation requires a GitHub personal access token with `repo` scope permissions. Make sure to add this token to your Port secrets as `ANOTHER_GITHUB_TOKEN`. +::: + +### Update PR with service relations + +This automation triggers after the first automation completes successfully and creates relations between the PR and the affected services. + +Follow the steps below to create the automation: + +1. Go back to the [automations](https://app.getport.io/settings/automations) page. + +2. Click on `+ Automation` and select `Edit JSON`. + +3. Copy and paste the following JSON schema: + +
+ Update PR with service relations automation (Click to expand) + + ```json showLineNumbers + { + "identifier": "update_pr_with_service", + "title": "Update PR with files changed", + "description": "Updates the pull request with relations to affected services", + "trigger": { + "type": "automation", + "event": { + "type": "RUN_UPDATED", + "actionIdentifier": "get_files_changed_for_a_pr" + }, + "condition": { + "type": "JQ", + "expressions": [ + ".diff.after.status == \"SUCCESS\"" + ], + "combinator": "and" + } + }, + "invocationMethod": { + "type": "UPSERT_ENTITY", + "blueprintIdentifier": "githubPullRequest", + "mapping": { + "identifier": "{{ .event.diff.before.payload.headers.Identifier | tostring }}", + "relations": { + "service": "{{ .event.diff.after.response[].filename | split(\"/\")[:-1] | join(\"/\") }}" + } + } + }, + "publish": true + } + ``` + +
+ +5. Click "Save" to create the automation. + +:::info Automation chain +This automation is chained to the first one, meaning it will only execute after the "Get files changed for a PR" automation completes successfully. The chain ensures proper sequencing of operations. +::: + +## Let's test it + +1. Create a new pull request in your GitHub repository. + +2. Check the PR in Port. + +3. You should see the services that were affected by the PR. + +4. You can also see the services that were affected by the PR in the PR details page. diff --git a/src/components/guides-section/consts.js b/src/components/guides-section/consts.js index 97c59e8c9e..bf44692f2e 100644 --- a/src/components/guides-section/consts.js +++ b/src/components/guides-section/consts.js @@ -1347,6 +1347,13 @@ export const availableGuides = [ tags: ["Incident management", "AI", "Automations"], logos: ["AI", "Slack", "PagerDuty"], link: "/guides/all/generate-incident-updates-with-ai", + }, + { + title: "Map PR's to services in a monorepo", + description: "Automatically map GitHub pull requests to services in a monorepo using file path analysis", + tags: ["SDLC", "GitHub", "Automations"], + logos: ["GitHub"], + link: "/guides/all/map-prs-to-services-in-monorepo", } ] From 9f394c356fde0886ca863790870a5c4c4271be06 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Tue, 12 Aug 2025 09:16:46 +0000 Subject: [PATCH 2/6] Enhance guide for mapping PRs to services in a monorepo by adding steps to create and update blueprints, including the new `file_change_url` property. Update automation configurations for fetching and updating PRs with file changes. --- .../all/map-prs-to-services-in-monorepo.md | 315 ++++++++++++------ temp-test-repo | 1 + 2 files changed, 212 insertions(+), 104 deletions(-) create mode 160000 temp-test-repo diff --git a/docs/guides/all/map-prs-to-services-in-monorepo.md b/docs/guides/all/map-prs-to-services-in-monorepo.md index afdff2c424..8169a136a0 100644 --- a/docs/guides/all/map-prs-to-services-in-monorepo.md +++ b/docs/guides/all/map-prs-to-services-in-monorepo.md @@ -22,7 +22,58 @@ This functionality streamlines monorepo management by enabling teams to quickly If you haven't installed the [GitHub integration](/build-your-software-catalog/sync-data-to-catalog/git/github), you'll need to create a blueprint for GitHub pull requests in Port. However, we highly recommend you install the GitHub integration to have the blueprint automatically set up for you. -

Create a blueprint for GitHub pull requests

+If you've already installed the GitHub integration you have to [update the pull request blueprint](#update-the-pull-request-blueprint) to include the +`file_change_url` property. + +### Create the repository blueprint + +1. Go to the [blueprints](https://app.getport.io/settings/blueprints) page of your portal. + +2. Click on `+ Blueprint`. + +3. Click on the `Edit JSON` button in the top right corner. + +4. Copy and paste the following JSON schema: + +
+ Repository blueprint (Click to expand) + + ```json showLineNumbers + { + "identifier": "githubRepository", + "title": "Repository", + "icon": "Github", + "schema": { + "properties": { + "readme": { + "title": "README", + "type": "string", + "format": "markdown" + }, + "url": { + "title": "Repository URL", + "type": "string", + "format": "url" + }, + "defaultBranch": { + "title": "Default branch", + "type": "string" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": {} + } + + ``` +
+ +5. Click "Save" to create the blueprint. + + +### Create the pull request blueprint 1. Go to the [blueprints](https://app.getport.io/settings/blueprints) page of your portal. @@ -37,92 +88,117 @@ However, we highly recommend you install the GitHub integration to have the blue ```json showLineNumbers { - "identifier": "githubPullRequest", - "title": "Pull Request", - "icon": "Github", - "schema": { + "identifier": "githubPullRequest", + "title": "Pull Request", + "icon": "Github", + "schema": { "properties": { - "creator": { + "creator": { "title": "Creator", "type": "string" - }, - "assignees": { + }, + "assignees": { "title": "Assignees", "type": "array" - }, - "reviewers": { + }, + "reviewers": { "title": "Reviewers", "type": "array" - }, - "status": { + }, + "status": { "title": "Status", "type": "string", "enum": ["merged", "open", "closed"], "enumColors": { - "merged": "purple", - "open": "green", - "closed": "red" + "merged": "purple", + "open": "green", + "closed": "red" } - }, - "closedAt": { + }, + "closedAt": { "title": "Closed At", "type": "string", "format": "date-time" - }, - "updatedAt": { + }, + "updatedAt": { "title": "Updated At", "type": "string", "format": "date-time" - }, - "mergedAt": { + }, + "mergedAt": { "title": "Merged At", "type": "string", "format": "date-time" - }, - "createdAt": { + }, + "createdAt": { "title": "Created At", "type": "string", "format": "date-time" - }, - "link": { + }, + "link": { "format": "url", "type": "string" - }, - "leadTimeHours": { + }, + "leadTimeHours": { "title": "Lead Time in hours", "type": "number" - } + }, + "file_change_url": { + "type": "string", + "title": "File change URL", + "format": "url" + } }, "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": { + }, + "mirrorProperties": {}, + "calculationProperties": { "days_old": { - "title": "Days Old", - "icon": "DefaultProperty", - "calculation": "(now / 86400) - (.properties.createdAt | capture(\"(?\\\\d{4}-\\\\d{2}-\\\\d{2})\") | .date | strptime(\"%Y-%m-%d\") | mktime / 86400) | floor", - "type": "number" + "title": "Days Old", + "icon": "DefaultProperty", + "calculation": "(now / 86400) - (.properties.createdAt | capture(\"(?\\\\d{4}-\\\\d{2}-\\\\d{2})\") | .date | strptime(\"%Y-%m-%d\") | mktime / 86400) | floor", + "type": "number" } - }, - "relations": { + }, + "relations": { "repository": { - "title": "Repository", - "target": "githubRepository", - "required": false, - "many": false + "title": "Repository", + "target": "githubRepository", + "required": false, + "many": false } - } + } } ``` 5. Click "Save" to create the blueprint. +### Update the pull request blueprint + +1. Go to the [blueprints](https://app.getport.io/settings/blueprints) page of your portal. + +2. Find the `githubPullRequest` blueprint and click on it. + +3. Click on the `Edit JSON` button in the top right corner. + +4. Add the snippet below to the `schema` section: + + ```json showLineNumbers + "file_change_url": { + "type": "string", + "title": "File change URL", + "format": "url" + } + ``` +5. Click "Save" to update the blueprint. ## Update the data source The first step is to configure how services are mapped from your monorepo structure. We'll use Port's file ingestion feature to automatically create service entities based on file paths. +

Add the service mapping configuration

+ Follow the steps below to update the data source: 1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page of your portal. @@ -160,6 +236,37 @@ Follow the steps below to update the data source: This configuration assumes each service has a `service.yml` file in its root directory. You can modify the path pattern to match your actual service configuration file (e.g., `**/package.json`, `**/docker-compose.yml`, etc.). ::: +

Update the pull request kind to include the file change URL

+ +1. Still in the [data sources](https://app.getport.io/settings/data-sources) page of your portal. + +2. Update the `pull-request` kind to include the `file_change_url` property. + +
+ Pull request kind configuration (Click to expand) + + ```yaml showLineNumbers + - kind: pull-request + selector: + query: 'true' + port: + entity: + mappings: + identifier: .id|tostring + title: .title + blueprint: '"githubPullRequest"' + properties: + status: .status + label: .labels + // highlight-start + file_change_url: .commits_url | split("/")[:8] | join("/") + "/files" + // highlight-end + // other properties... + ``` +
+ +3. Click "Save" to update the data source. + ## Set up automations Now we'll create a two-step automation workflow that: @@ -182,37 +289,37 @@ This automation triggers when a new pull request is created and fetches the list Get files changed automation (Click to expand) ```json showLineNumbers - { - "identifier": "get_files_changed_for_a_pr", - "title": "Get files changed for a PR", - "description": "Fetches the list of files changed in a pull request", - "trigger": { - "type": "automation", - "event": { - "type": "ENTITY_CREATED", - "blueprintIdentifier": "githubPullRequest" - }, - "condition": { - "type": "JQ", - "expressions": [], - "combinator": "and" - } - }, - "invocationMethod": { - "type": "WEBHOOK", - "url": "{{ .event.diff.after.properties.file_change_url }}", - "agent": false, - "synchronized": true, - "method": "GET", - "headers": { - "Authorization": "Bearer {{ .secrets.ANOTHER_GITHUB_TOKEN }}", - "X-GitHub-Api-Version": "2022-11-28", - "Identifier": "{{ .event.context.entityIdentifier | tostring }}" - }, - "body": {} - }, - "publish": true - } + { + "identifier": "get_files_changed_for_a_pr", + "title": "Get files changed for a PR", + "description": "", + "trigger": { + "type": "automation", + "event": { + "type": "ENTITY_UPDATED", + "blueprintIdentifier": "githubPullRequest" + }, + "condition": { + "type": "JQ", + "expressions": [], + "combinator": "and" + } + }, + "invocationMethod": { + "type": "WEBHOOK", + "url": "{{ .event.diff.after.properties.file_change_url }}", + "agent": false, + "synchronized": true, + "method": "GET", + "headers": { + "Authorization": "Bearer {{ .secrets.YOUR_GITHUB_TOKEN }}", + "X-GitHub-Api-Version": "2022-11-28", + "Identifier": "{{ .event.context.entityIdentifier | tostring }}" + }, + "body": {} + }, + "publish": true + } ``` @@ -220,7 +327,7 @@ This automation triggers when a new pull request is created and fetches the list 5. Click "Save" to create the automation. :::info GitHub token requirement -This automation requires a GitHub personal access token with `repo` scope permissions. Make sure to add this token to your Port secrets as `ANOTHER_GITHUB_TOKEN`. +This automation requires a GitHub personal access token with `repo` scope permissions. Make sure to add this token to your Port secrets as `YOUR_GITHUB_TOKEN`. ::: ### Update PR with service relations @@ -239,36 +346,36 @@ Follow the steps below to create the automation: Update PR with service relations automation (Click to expand) ```json showLineNumbers - { - "identifier": "update_pr_with_service", - "title": "Update PR with files changed", - "description": "Updates the pull request with relations to affected services", - "trigger": { - "type": "automation", - "event": { - "type": "RUN_UPDATED", - "actionIdentifier": "get_files_changed_for_a_pr" - }, - "condition": { - "type": "JQ", - "expressions": [ - ".diff.after.status == \"SUCCESS\"" - ], - "combinator": "and" - } - }, - "invocationMethod": { - "type": "UPSERT_ENTITY", - "blueprintIdentifier": "githubPullRequest", - "mapping": { - "identifier": "{{ .event.diff.before.payload.headers.Identifier | tostring }}", - "relations": { - "service": "{{ .event.diff.after.response[].filename | split(\"/\")[:-1] | join(\"/\") }}" - } - } - }, - "publish": true - } + { + "identifier": "update_pr_with_service", + "title": "Update PR with files changed", + "description": "", + "trigger": { + "type": "automation", + "event": { + "type": "RUN_UPDATED", + "actionIdentifier": "get_files_changed_for_a_pr" + }, + "condition": { + "type": "JQ", + "expressions": [ + ".diff.after.status == \"SUCCESS\"" + ], + "combinator": "and" + } + }, + "invocationMethod": { + "type": "UPSERT_ENTITY", + "blueprintIdentifier": "githubPullRequest", + "mapping": { + "identifier": "{{ .event.diff.before.payload.headers.Identifier | tostring }}", + "relations": { + "service": "{{ .event.diff.before.response | map(.filename | split(\"/\")[:-1] | join(\"/\")) }}" + } + } + }, + "publish": true + } ``` diff --git a/temp-test-repo b/temp-test-repo new file mode 160000 index 0000000000..bfae9f8a35 --- /dev/null +++ b/temp-test-repo @@ -0,0 +1 @@ +Subproject commit bfae9f8a3580237610d951a967f1e2339f37cda5 From 71ce54193d400194e1d872a77c6c339938a5bbdc Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Thu, 14 Aug 2025 15:23:53 +0000 Subject: [PATCH 3/6] Update guide for mapping PRs to services in a monorepo by adding a new `services` section in the blueprint configuration, including detailed steps for integration. --- .../all/map-prs-to-services-in-monorepo.md | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/guides/all/map-prs-to-services-in-monorepo.md b/docs/guides/all/map-prs-to-services-in-monorepo.md index 8169a136a0..68ae701f6e 100644 --- a/docs/guides/all/map-prs-to-services-in-monorepo.md +++ b/docs/guides/all/map-prs-to-services-in-monorepo.md @@ -166,6 +166,12 @@ If you've already installed the GitHub integration you have to [update the pull "target": "githubRepository", "required": false, "many": false + }, + "services": { + "title": "Services", + "target": "service", + "required": false, + "many": true } } } @@ -191,7 +197,19 @@ If you've already installed the GitHub integration you have to [update the pull "format": "url" } ``` -5. Click "Save" to update the blueprint. + +5. Add the following snippet to the `relations` section: + + ```json showLineNumbers + "services": { + "title": "Services", + "target": "service", + "required": false, + "many": true + } + ``` + +6. Click "Save" to update the blueprint. ## Update the data source From 4216cfc83499e3daf688ac14fae895c25ed74c3c Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Thu, 14 Aug 2025 15:31:04 +0000 Subject: [PATCH 4/6] Remove subproject reference and update language in the guide for mapping PRs to services in a monorepo for clarity. --- docs/guides/all/map-prs-to-services-in-monorepo.md | 4 ++-- temp-test-repo | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) delete mode 160000 temp-test-repo diff --git a/docs/guides/all/map-prs-to-services-in-monorepo.md b/docs/guides/all/map-prs-to-services-in-monorepo.md index 68ae701f6e..4a4fcefc84 100644 --- a/docs/guides/all/map-prs-to-services-in-monorepo.md +++ b/docs/guides/all/map-prs-to-services-in-monorepo.md @@ -410,6 +410,6 @@ This automation is chained to the first one, meaning it will only execute after 2. Check the PR in Port. -3. You should see the services that were affected by the PR. +3. Check the services that were affected by the PR. -4. You can also see the services that were affected by the PR in the PR details page. +4. Check the [Audit log](https://app.getport.io/settings/AuditLog) to see the chain of actions diff --git a/temp-test-repo b/temp-test-repo deleted file mode 160000 index bfae9f8a35..0000000000 --- a/temp-test-repo +++ /dev/null @@ -1 +0,0 @@ -Subproject commit bfae9f8a3580237610d951a967f1e2339f37cda5 From c55b3454c5bea43c1625da7dd8593b50f76187a1 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Wed, 20 Aug 2025 11:28:59 +0000 Subject: [PATCH 5/6] Update documentation for mapping PRs to services in a monorepo, clarifying terminology and enhancing instructions. Change title to remove apostrophe and ensure consistency in referring to sub-components as 'services'. --- .../all/map-prs-to-services-in-monorepo.md | 30 ++++++++++++------- src/components/guides-section/consts.js | 2 +- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/guides/all/map-prs-to-services-in-monorepo.md b/docs/guides/all/map-prs-to-services-in-monorepo.md index 4a4fcefc84..53fb6c304e 100644 --- a/docs/guides/all/map-prs-to-services-in-monorepo.md +++ b/docs/guides/all/map-prs-to-services-in-monorepo.md @@ -3,20 +3,26 @@ displayed_sidebar: null description: Automatically map pull requests to services in a monorepo using file path analysis --- -# Map PR's to services in a monorepo +# Map PRs to services in a monorepo ## Overview -This guide will help you implement an automation in Port that automatically maps GitHub pull requests to services in your monorepo based on the files that were changed. -This functionality streamlines monorepo management by enabling teams to quickly understand which services are affected by each change without manual analysis. +This guide demonstrates how to implement an automation in Port to map GitHub pull requests to sub-components in your monorepo based on the files that were changed. + +This functionality streamlines monorepo management by enabling teams to quickly understand which sub-components are affected by each change without manual analysis. In this guide will refer to those sub-components as 'services'. ## Prerequisites - Complete the [onboarding process](/getting-started/overview). -- A GitHub repository with a monorepo structure containing multiple services. -- Services organized in directories with a `service.yml` file (or similar configuration file). +- A GitHub repository with a monorepo structure containing multiple sub-components. - Port's [GitHub App](/build-your-software-catalog/sync-data-to-catalog/git/github/github.md) installed. - Access to GitHub API tokens for automation. +:::info Monorepo structure assumptions +This guide assumes that the sub-components are organized in directories with a `service.yml` file (or similar configuration file). You can modify the path pattern to match your actual service configuration file (e.g., `**/package.json`, `**/docker-compose.yml`, etc.). +::: + + + ## Set up data model If you haven't installed the [GitHub integration](/build-your-software-catalog/sync-data-to-catalog/git/github), you'll need to create a blueprint for GitHub pull requests in Port. @@ -182,6 +188,8 @@ If you've already installed the GitHub integration you have to [update the pull ### Update the pull request blueprint +Skip this step if you just manually [created the pull request blueprint](#create-the-pull-request-blueprint). + 1. Go to the [blueprints](https://app.getport.io/settings/blueprints) page of your portal. 2. Find the `githubPullRequest` blueprint and click on it. @@ -233,7 +241,7 @@ Follow the steps below to update the data source: selector: query: 'true' files: - - path: '**/service.yml' + - path: '**/service.yml' # or your actual service configuration file repos: - platform port: @@ -246,12 +254,12 @@ Follow the steps below to update the data source: - **Note**: Adjust the `path` pattern and `repos` list according to your monorepo structure. The `identifier` mapping extracts the directory path above the `service.yml` file, which becomes the service identifier. + **Note**: Adjust the `path` pattern and `repos` list according to your monorepo structure. The `identifier` mapping extracts the directory path above the service configuration file (e.g., `service.yml`), which becomes the service identifier. -6. Click "Save" to create the data source. +6. Click "Save & Resync" to update the data source. :::tip Service file structure -This configuration assumes each service has a `service.yml` file in its root directory. You can modify the path pattern to match your actual service configuration file (e.g., `**/package.json`, `**/docker-compose.yml`, etc.). +This configuration assumes each service (sub-component) has a `service.yml` file in its root directory. You can modify the path pattern to match your actual service configuration file (e.g., `**/package.json`, `**/docker-compose.yml`, etc.). :::

Update the pull request kind to include the file change URL

@@ -283,7 +291,7 @@ This configuration assumes each service has a `service.yml` file in its root dir ``` -3. Click "Save" to update the data source. +3. Click "Save & Resync" to update the data source. ## Set up automations @@ -314,7 +322,7 @@ This automation triggers when a new pull request is created and fetches the list "trigger": { "type": "automation", "event": { - "type": "ENTITY_UPDATED", + "type": "ENTITY_CREATED", "blueprintIdentifier": "githubPullRequest" }, "condition": { diff --git a/src/components/guides-section/consts.js b/src/components/guides-section/consts.js index 6d9b8ca5d3..faa2a5b596 100644 --- a/src/components/guides-section/consts.js +++ b/src/components/guides-section/consts.js @@ -1344,7 +1344,7 @@ export const availableGuides = [ link: "/guides/all/generate-incident-updates-with-ai", }, { - title: "Map PR's to services in a monorepo", + title: "Map PRs to services in a monorepo", description: "Automatically map GitHub pull requests to services in a monorepo using file path analysis", tags: ["SDLC", "GitHub", "Automations"], logos: ["GitHub"], From 9497e74e0224609750932062f7fa376320d3098e Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Wed, 20 Aug 2025 15:28:00 +0000 Subject: [PATCH 6/6] Update GitHub pull request blueprint setup instructions in the documentation, clarifying the automatic creation of blueprints after installing Port's GitHub App and removing outdated steps for manual blueprint creation. --- .../all/map-prs-to-services-in-monorepo.md | 162 +----------------- 1 file changed, 1 insertion(+), 161 deletions(-) diff --git a/docs/guides/all/map-prs-to-services-in-monorepo.md b/docs/guides/all/map-prs-to-services-in-monorepo.md index 53fb6c304e..26807ae15d 100644 --- a/docs/guides/all/map-prs-to-services-in-monorepo.md +++ b/docs/guides/all/map-prs-to-services-in-monorepo.md @@ -25,171 +25,11 @@ This guide assumes that the sub-components are organized in directories with a ` ## Set up data model -If you haven't installed the [GitHub integration](/build-your-software-catalog/sync-data-to-catalog/git/github), you'll need to create a blueprint for GitHub pull requests in Port. -However, we highly recommend you install the GitHub integration to have the blueprint automatically set up for you. +After installing Port's [GitHub App](/build-your-software-catalog/sync-data-to-catalog/git/github/github.md), several blueprints are automatically created in your portal, including the `githubPullRequest` blueprint. However you need to update the blueprint with some additional properties in this setup. -If you've already installed the GitHub integration you have to [update the pull request blueprint](#update-the-pull-request-blueprint) to include the -`file_change_url` property. - -### Create the repository blueprint - -1. Go to the [blueprints](https://app.getport.io/settings/blueprints) page of your portal. - -2. Click on `+ Blueprint`. - -3. Click on the `Edit JSON` button in the top right corner. - -4. Copy and paste the following JSON schema: - -
- Repository blueprint (Click to expand) - - ```json showLineNumbers - { - "identifier": "githubRepository", - "title": "Repository", - "icon": "Github", - "schema": { - "properties": { - "readme": { - "title": "README", - "type": "string", - "format": "markdown" - }, - "url": { - "title": "Repository URL", - "type": "string", - "format": "url" - }, - "defaultBranch": { - "title": "Default branch", - "type": "string" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": {} - } - - ``` -
- -5. Click "Save" to create the blueprint. - - -### Create the pull request blueprint - -1. Go to the [blueprints](https://app.getport.io/settings/blueprints) page of your portal. - -2. Click on `+ Blueprint`. - -3. Click on the `Edit JSON` button in the top right corner. - -4. Copy and paste the following JSON schema: - -
- GitHub pull request blueprint (Click to expand) - - ```json showLineNumbers - { - "identifier": "githubPullRequest", - "title": "Pull Request", - "icon": "Github", - "schema": { - "properties": { - "creator": { - "title": "Creator", - "type": "string" - }, - "assignees": { - "title": "Assignees", - "type": "array" - }, - "reviewers": { - "title": "Reviewers", - "type": "array" - }, - "status": { - "title": "Status", - "type": "string", - "enum": ["merged", "open", "closed"], - "enumColors": { - "merged": "purple", - "open": "green", - "closed": "red" - } - }, - "closedAt": { - "title": "Closed At", - "type": "string", - "format": "date-time" - }, - "updatedAt": { - "title": "Updated At", - "type": "string", - "format": "date-time" - }, - "mergedAt": { - "title": "Merged At", - "type": "string", - "format": "date-time" - }, - "createdAt": { - "title": "Created At", - "type": "string", - "format": "date-time" - }, - "link": { - "format": "url", - "type": "string" - }, - "leadTimeHours": { - "title": "Lead Time in hours", - "type": "number" - }, - "file_change_url": { - "type": "string", - "title": "File change URL", - "format": "url" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": { - "days_old": { - "title": "Days Old", - "icon": "DefaultProperty", - "calculation": "(now / 86400) - (.properties.createdAt | capture(\"(?\\\\d{4}-\\\\d{2}-\\\\d{2})\") | .date | strptime(\"%Y-%m-%d\") | mktime / 86400) | floor", - "type": "number" - } - }, - "relations": { - "repository": { - "title": "Repository", - "target": "githubRepository", - "required": false, - "many": false - }, - "services": { - "title": "Services", - "target": "service", - "required": false, - "many": true - } - } - } - ``` -
- -5. Click "Save" to create the blueprint. ### Update the pull request blueprint -Skip this step if you just manually [created the pull request blueprint](#create-the-pull-request-blueprint). - 1. Go to the [blueprints](https://app.getport.io/settings/blueprints) page of your portal. 2. Find the `githubPullRequest` blueprint and click on it.