From 38736860792a52c013abd41c3bb80b597f87b625 Mon Sep 17 00:00:00 2001 From: Dennis Bilson Date: Fri, 21 Nov 2025 13:41:38 +0000 Subject: [PATCH 1/7] Add repoFilter tab to Bitbucket Cloud advanced documentation --- .../git/bitbucket/bitbucket-cloud/advanced.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md index aaf1dc7a76..66c9f29df0 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md @@ -34,6 +34,16 @@ The `createMissingRelatedEntities` parameter is used to enable the creation of m + + +The `repoFilter` parameter is used to [narrow down data fetched](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-get) for repositories with a specific set of query parameters. + +- **Default value**: `None` to fetch all repositories. +- **Use case**: set this in your configuration if you want to opt into this behavior. + - **role**: Users can optionally specify role with one of the following values: `member`, `contributor`, `admin`, `owner`. + - **q**: Users can optionally specify q as a search query string to filter repositories. + + From 0db5190240068cff969c1f67169085601b61dd84 Mon Sep 17 00:00:00 2001 From: Dennis Bilson Date: Fri, 21 Nov 2025 13:55:03 +0000 Subject: [PATCH 2/7] Refine Bitbucket Cloud advanced docs for `repoFilter` usage and parameter descriptions --- .../git/bitbucket/bitbucket-cloud/advanced.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md index 66c9f29df0..c15ace195e 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md @@ -36,12 +36,12 @@ The `createMissingRelatedEntities` parameter is used to enable the creation of m -The `repoFilter` parameter is used to [narrow down data fetched](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-get) for repositories with a specific set of query parameters. +Use the `repoFilter` parameter is to [narrow down data fetched](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-get) for repositories with a specific set of query parameters. - **Default value**: `None` to fetch all repositories. - **Use case**: set this in your configuration if you want to opt into this behavior. - - **role**: Users can optionally specify role with one of the following values: `member`, `contributor`, `admin`, `owner`. - - **q**: Users can optionally specify q as a search query string to filter repositories. + - **role**: Specify role with one of the following values: `member`, `contributor`, `admin`, `owner`. + - **q**: Specify q as a search query string to filter repositories. From e4e311f52d8b45a139ede8a08046f757c6be64cd Mon Sep 17 00:00:00 2001 From: Dennis Bilson Date: Fri, 21 Nov 2025 14:14:59 +0000 Subject: [PATCH 3/7] Expand Bitbucket Cloud advanced docs with `repoFilter` role and query examples --- .../git/bitbucket/bitbucket-cloud/advanced.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md index c15ace195e..2df71b5e20 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md @@ -41,7 +41,22 @@ Use the `repoFilter` parameter is to [narrow down data fetched](https://develope - **Default value**: `None` to fetch all repositories. - **Use case**: set this in your configuration if you want to opt into this behavior. - **role**: Specify role with one of the following values: `member`, `contributor`, `admin`, `owner`. + + ```yaml showLineNumbers + repoFilter: + # highlight-next-line + role: "admin" + resources: + # remaining resource definitions omitted for brevity + ``` - **q**: Specify q as a search query string to filter repositories. + ```yaml showLineNumbers + repoFilter: + # highlight-next-line + q: 'parent.owner.nickname = ""' + resources: + # remaining resource definitions omitted for brevity + ``` From 22094199feee8257b94593d428371903d5c41eec Mon Sep 17 00:00:00 2001 From: Dennis Bilson Date: Fri, 21 Nov 2025 14:19:01 +0000 Subject: [PATCH 4/7] Fix typo in Bitbucket Cloud advanced docs for `repoFilter` parameter descriptions --- .../git/bitbucket/bitbucket-cloud/advanced.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md index 2df71b5e20..f109fa8547 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md @@ -40,7 +40,7 @@ Use the `repoFilter` parameter is to [narrow down data fetched](https://develope - **Default value**: `None` to fetch all repositories. - **Use case**: set this in your configuration if you want to opt into this behavior. - - **role**: Specify role with one of the following values: `member`, `contributor`, `admin`, `owner`. + - **role**: Specify with one of the following values: `member`, `contributor`, `admin`, `owner`. ```yaml showLineNumbers repoFilter: @@ -49,7 +49,8 @@ Use the `repoFilter` parameter is to [narrow down data fetched](https://develope resources: # remaining resource definitions omitted for brevity ``` - - **q**: Specify q as a search query string to filter repositories. + - **q**: Specify as a search query string to filter repositories. + ```yaml showLineNumbers repoFilter: # highlight-next-line From 34a1ffa23dc0b76384a2cfc5cb18129df797083c Mon Sep 17 00:00:00 2001 From: Dennis Bilson Date: Mon, 8 Dec 2025 08:37:52 +0000 Subject: [PATCH 5/7] docs: Rename `repoFilter` parameter `q` to `query` in Bitbucket Cloud advanced configuration. --- .../git/bitbucket/bitbucket-cloud/advanced.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md index f109fa8547..c60437b53b 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/advanced.md @@ -49,12 +49,12 @@ Use the `repoFilter` parameter is to [narrow down data fetched](https://develope resources: # remaining resource definitions omitted for brevity ``` - - **q**: Specify as a search query string to filter repositories. + - **query**: Specify as a search query string to filter repositories. ```yaml showLineNumbers repoFilter: # highlight-next-line - q: 'parent.owner.nickname = ""' + query: 'parent.owner.nickname = ""' resources: # remaining resource definitions omitted for brevity ``` From 412d0e1b8fb9368c15dd890caf52ee25ba3c296c Mon Sep 17 00:00:00 2001 From: Dennis Bilson Date: Wed, 10 Dec 2025 10:24:01 +0000 Subject: [PATCH 6/7] Update examples.md --- .../git/bitbucket/bitbucket-cloud/examples.md | 97 ++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md index 678e6d80bf..65f993c15b 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md @@ -1,7 +1,8 @@ --- sidebar_position: 2 --- - +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import MicroserviceBlueprint from './\_bitbucket_integration_example_repository_blueprint.mdx' import PRBlueprint from './\_bitbucket_integration_example_pull_request_blueprint.mdx' import PortAppConfig from './\_bitbucket_integration_example_port_app_config.mdx' @@ -25,6 +26,100 @@ The following example demonstrates how to ingest your Bitbucket projects, reposi +### Repository configuration options + + + + + +The `userRole` selector allows you to filter repositories based on the user role. You can specify only one user role to include in the sync. + +Allowed values: +- `owner`: Repositories owned by the current user. +- `member`: Repositories to which the user has explicit read access. +- `admin`: Repositories to which the user has explicit administrator access. +- `contributor`: Repositories to which the user has explicit write access. + +By default, if not specified, no user role filter will be applied. + +```yaml + - kind: repository + selector: + query: 'true' + # highlight-next-line + userRole: owner +``` + + + + + +The `repoQuery` selector allows you to filter repositories based on a custom query. You can specify a custom query to include in the sync. + +```yaml + - kind: repository + selector: + query: 'true' + # highlight-next-line + repoQuery: 'language="python"' +``` + + + + + +### Pull request configuration options + + + + + +The `states` selector allows you to filter pull requests based on their state. You can specify one or more states to include in the sync. + +Allowed values: +- `OPEN`: Pull requests that are currently open. +- `MERGED`: Pull requests that have been merged. +- `DECLINED`: Pull requests that have been declined. +- `SUPERSEDED`: Pull requests that have been superseded. + +By default, if not specified, only `OPEN` pull requests will be synced. + +```yaml + - kind: pull-request + selector: + query: 'true' + # highlight-next-line + states: + - OPEN + - MERGED + - DECLINED + - SUPERSEDED +``` + + + + +The `maxResults` selector allows you to limit the number of pull requests synced. This helps you control the amount of data being synced and reduce the time taken to sync. + +The value represents the maximum number of pull requests to sync. For example, setting it to `100` will only sync the first 100 pull requests. + +:::info Important +The `maxResults` parameter only affects pull requests that are not in the "open" state. Open pull requests will always be synced regardless of their last update time. +::: + +By default, if not specified, it is set to `100` pull requests. + +```yaml + - kind: pull-request + selector: + query: 'true' + # highlight-next-line + maxResults: 1000 +``` + + + + :::tip - Refer to the [installation](installation.md) guide to learn more about the `port-app-config.yml` installation process; From 1331ba5f99942b83c68b4ea6f0a57ce30a498329 Mon Sep 17 00:00:00 2001 From: Dennis Bilson Date: Wed, 10 Dec 2025 13:38:32 +0000 Subject: [PATCH 7/7] Update examples.md --- .../git/bitbucket/bitbucket-cloud/examples.md | 46 ++++--------------- 1 file changed, 8 insertions(+), 38 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md index 65f993c15b..70d0f7bdf6 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md @@ -70,56 +70,25 @@ The `repoQuery` selector allows you to filter repositories based on a custom que ### Pull request configuration options - - - - -The `states` selector allows you to filter pull requests based on their state. You can specify one or more states to include in the sync. - -Allowed values: -- `OPEN`: Pull requests that are currently open. -- `MERGED`: Pull requests that have been merged. -- `DECLINED`: Pull requests that have been declined. -- `SUPERSEDED`: Pull requests that have been superseded. +The `pullRequestQuery` selector allows you to filter pull requests based on a custom query. You can specify a custom query per the official BitBucket filtering and sorting specifications to include in the sync. -By default, if not specified, only `OPEN` pull requests will be synced. +By default, if not specified, all open pull requests will be ingested. ```yaml - kind: pull-request selector: query: 'true' # highlight-next-line - states: - - OPEN - - MERGED - - DECLINED - - SUPERSEDED + pullRequestQuery: 'state="OPEN" OR (state="MERGED" AND updated_on > "2025-12-10T14:00:00-07:00")' ``` - - - - -The `maxResults` selector allows you to limit the number of pull requests synced. This helps you control the amount of data being synced and reduce the time taken to sync. -The value represents the maximum number of pull requests to sync. For example, setting it to `100` will only sync the first 100 pull requests. +:::warning Performance impact +Non-open pull requests (such as `MERGED` or `DECLINED`) can accumulate to an extremely large volume over time, which may significantly increase the time required to complete a resync for the integration. -:::info Important -The `maxResults` parameter only affects pull requests that are not in the "open" state. Open pull requests will always be synced regardless of their last update time. +To prevent performance degradation, if you intend to ingest non-open pull requests, you must add a filtering criteria such as `updated_on` to limit the number of items ingested. +The example above demonstrates this by retrieving all `OPEN` pull requests, while limiting `MERGED` pull requests to those updated after a specific timestamp. ::: -By default, if not specified, it is set to `100` pull requests. - -```yaml - - kind: pull-request - selector: - query: 'true' - # highlight-next-line - maxResults: 1000 -``` - - - - :::tip - Refer to the [installation](installation.md) guide to learn more about the `port-app-config.yml` installation process; @@ -127,6 +96,7 @@ By default, if not specified, it is set to `100` pull requests. - Click [Here](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-workspaces/#api-workspaces-workspace-projects-get) for the Bitbucket project object structure. - Click [Here](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-repo-slug-get) for the Bitbucket repository object structure. - Click [Here](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/#api-repositories-workspace-repo-slug-pullrequests-pull-request-id-get) for the Bitbucket pull request object structure. +- Click [Here](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#filtering) for the Bitbucket filtering and sorting API. ::: After creating the blueprints and updating the mapping, you will see new entities in Port matching your repositories alongside their README.md file contents and pull requests.