From 2dcd02fbd630151262e447adcf45339d069c6475 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Thu, 13 Nov 2025 13:35:24 +0100 Subject: [PATCH 1/3] fix: update doc --- .../git/github-ocean/examples.md | 10 ++++++- .../_file_repo_app_config.mdx | 2 +- .../git/github-ocean/github-ocean.md | 26 +++++++++++++------ 3 files changed, 28 insertions(+), 10 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md index bf70f8c633..7b4a1cf9a5 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md @@ -175,13 +175,21 @@ The following example demonstrates how to ingest your GitHub repositories and th To retrieve the root folders of your monorepo, use the following syntax in your `port-app-config.yml`: +::::info Organization and repository filtering for folders +Both `organization` and `repos` under `folders` are optional. You can: +- Specify only `organization`: scan all repositories in that organization for matching folders. +- Specify only `repos`: scan only those repositories across accessible organizations. +- Omit both: scan all accessible repositories for matching folders. +Use `path` and `repositoryType` to scope results and improve performance. +:::: + ```yaml - kind: folder selector: query: "true" # JQ boolean query. If evaluated to false - skip syncing the object. folders: # Specify the repositories and folders to include under this relative path. - path: "*" # Relative path to the folders within the repositories. - repos: # List of repositories to include folders from. + repos: # Optional: list repositories to include; omit to scan all repos - name: backend-service - name: frontend-service ``` diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx index 00836c1085..37876f0300 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx @@ -26,7 +26,7 @@ resources: files: - path: 'README.md' organization: my-org # Optional if githubOrganization is set; required if not set - repos: + repos: # Optional: list repositories to include; omit to scan all repos - name: test-repo branch: main port: diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md index 4f3b412536..2286a299b5 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md @@ -210,9 +210,19 @@ For example, say you want to manage your `package.json` files in Port. One optio The following configuration fetches all `package.json` files from "MyRepo" and "MyOtherRepo", and creates an entity for each of them, based on the `manifest` blueprint: -:::info Organization field in file selectors -The `organization` field is optional when `githubOrganization` is set in the environment variables and required when it is not provided (e.g., Classic PAT with multiple organizations defined in your port mapping). -::: +:::::info Organization and repository filtering +Both `organization` and `repos` in file selectors are optional. You can: +- Specify only `organization`: scan all repositories in that organization (respecting `repositoryType`). +- Specify only `repos`: scan only those repositories across all accessible organizations. +- Omit both: scan all repositories accessible to your credentials. + +When scanning broadly, the integration scope depends on your credentials: +- With GitHub App or fine‑grained PAT: all repositories in the installed/specified organization. +- With classic PAT: all repositories across all organizations the token can access. +Use `repositoryType` and precise `path` patterns to reduce scope. + +Note: Omitting `organization` and `repos` will scan all accessible repositories. For large orgs, expect longer resyncs and higher GitHub API usage. Narrow scope with `repos`, `repositoryType`, and specific `path` patterns. +:::::
Package file mapping example (click to expand) @@ -224,8 +234,8 @@ resources: files: # Note that glob patterns are supported, so you can use wildcards to match multiple files - path: '**/package.json' - organization: my-org # Optional if githubOrganization is set; required if not set - # The `repos` key can be used to filter the repositories and branch where files should be fetched + organization: my-org # Optional; omit to scan all orgs in scope + # Optional: use `repos` to filter repositories/branches; omit to scan all repos repos: - name: MyRepo branch: main @@ -754,7 +764,7 @@ resources: files: - path: '**/package.json' organization: my-org # Optional if githubOrganization is set; required if not set - # Note that in this case we are fetching from a specific repository + # Optional: you can target specific repositories here; omit to scan all repos repos: - name: MyRepo branch: main @@ -811,9 +821,9 @@ resources: query: 'true' files: - path: values.yaml - organization: my-org # Optional if githubOrganization is set; required if not set + organization: my-org # Optional; omit to scan all orgs in scope skipParsing: true - repos: + repos: # Optional: omit to scan all repos - name: MyRepo branch: main port: From 9b78a7ff05ca1b66cc972cf66f89937379f80140 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Thu, 13 Nov 2025 16:20:14 +0100 Subject: [PATCH 2/3] fix: handle formatting --- .../sync-data-to-catalog/git/github-ocean/examples.md | 4 ++-- .../examples/example-file-kind/_file_repo_app_config.mdx | 2 +- .../sync-data-to-catalog/git/github-ocean/github-ocean.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md index 7b4a1cf9a5..681404a514 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md @@ -183,13 +183,13 @@ Both `organization` and `repos` under `folders` are optional. You can: Use `path` and `repositoryType` to scope results and improve performance. :::: -```yaml +```yaml showLineNumbers - kind: folder selector: query: "true" # JQ boolean query. If evaluated to false - skip syncing the object. folders: # Specify the repositories and folders to include under this relative path. - path: "*" # Relative path to the folders within the repositories. - repos: # Optional: list repositories to include; omit to scan all repos + repos: # Optional: list repositories to include (omit to scan all repos) - name: backend-service - name: frontend-service ``` diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx index 37876f0300..8815090a8a 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx @@ -26,7 +26,7 @@ resources: files: - path: 'README.md' organization: my-org # Optional if githubOrganization is set; required if not set - repos: # Optional: list repositories to include; omit to scan all repos + repos: # Optional: list repositories to include (omit to scan all repos) - name: test-repo branch: main port: diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md index 2286a299b5..ba381aa110 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md @@ -764,7 +764,7 @@ resources: files: - path: '**/package.json' organization: my-org # Optional if githubOrganization is set; required if not set - # Optional: you can target specific repositories here; omit to scan all repos + # Optional: you can target specific repositories here (omit to scan all repos) repos: - name: MyRepo branch: main @@ -821,7 +821,7 @@ resources: query: 'true' files: - path: values.yaml - organization: my-org # Optional; omit to scan all orgs in scope + organization: my-org # Optional, omit to scan all orgs in scope skipParsing: true repos: # Optional: omit to scan all repos - name: MyRepo From 0aee25c1f17ef7ee886391dcbe4b5bc96aa98142 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Thu, 13 Nov 2025 16:23:59 +0100 Subject: [PATCH 3/3] fix: handle formating --- .../examples/example-file-kind/_file_repo_app_config.mdx | 2 +- .../examples/example-file-kind/_package_json_app_config.mdx | 2 +- .../_github_exporter_example_monorepo_port_app_config.mdx | 2 +- .../sync-data-to-catalog/git/github-ocean/github-ocean.md | 6 +++--- .../sync-data-to-catalog/git/github-ocean/gitops/gitops.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx index 8815090a8a..2a2241332d 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx @@ -25,7 +25,7 @@ resources: query: 'true' files: - path: 'README.md' - organization: my-org # Optional if githubOrganization is set; required if not set + organization: my-org # Optional if githubOrganization is set (required if not set) repos: # Optional: list repositories to include (omit to scan all repos) - name: test-repo branch: main diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_package_json_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_package_json_app_config.mdx index 016d13224a..c6f4e98b1f 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_package_json_app_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_package_json_app_config.mdx @@ -8,7 +8,7 @@ query: 'true' files: - path: '**/package.json' - organization: my-org # Optional if githubOrganization is set; required if not set + organization: my-org # Optional if githubOrganization is set (required if not set) repos: - name: vscode branch: main diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-monorepo/_github_exporter_example_monorepo_port_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-monorepo/_github_exporter_example_monorepo_port_app_config.mdx index 853c1d946f..944b76c233 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-monorepo/_github_exporter_example_monorepo_port_app_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-monorepo/_github_exporter_example_monorepo_port_app_config.mdx @@ -9,7 +9,7 @@ resources: query: "true" # JQ boolean query. If evaluated to false - skip syncing the object. folders: # Specify the repositories and folders to include under this relative path. - path: apps/* # Relative path to the folders within the repositories. - organization: my-org # Optional if githubOrganization is set; required if not set + organization: my-org # Optional if githubOrganization is set (required if not set) repos: # List of repositories to include folders from. - name: backend-service branch: main diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md index ba381aa110..b3e6af26f2 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md @@ -234,8 +234,8 @@ resources: files: # Note that glob patterns are supported, so you can use wildcards to match multiple files - path: '**/package.json' - organization: my-org # Optional; omit to scan all orgs in scope - # Optional: use `repos` to filter repositories/branches; omit to scan all repos + organization: my-org # Optional, omit to scan all orgs in scope + # Optional: use `repos` to filter repositories/branches (omit to scan all repos) repos: - name: MyRepo branch: main @@ -763,7 +763,7 @@ resources: query: 'true' files: - path: '**/package.json' - organization: my-org # Optional if githubOrganization is set; required if not set + organization: my-org # Optional if githubOrganization is set (required if not set) # Optional: you can target specific repositories here (omit to scan all repos) repos: - name: MyRepo diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/gitops.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/gitops.md index 22d2aba330..9acd1e75a6 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/gitops.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/gitops.md @@ -137,7 +137,7 @@ resources: query: 'true' files: - path: package.json - organization: my-org # Optional if githubOrganization is set; required if not set + organization: my-org # Optional if githubOrganization is set (required if not set) repos: - name: my-repo branch: main