From b5415bf63cae9e09d8e5dfa45a0ed3eed056336a Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Mon, 13 Oct 2025 17:44:46 +0100 Subject: [PATCH 01/10] fix: add multi orgs support --- .../_github_docker_parameters.mdx | 4 +- .../_github_exporter_supported_resources.mdx | 1 + ...ithub_exporter_example_port_app_config.mdx | 2 + ..._exporter_example_repository_blueprint.mdx | 9 ++- .../_file_repo_app_config.mdx | 2 + .../_package_json_app_config.mdx | 1 + ...orter_example_monorepo_port_app_config.mdx | 1 + ...xporter_example_organization_blueprint.mdx | 39 ++++++++++++ ...r_example_organization_port_app_config.mdx | 39 ++++++++++++ .../git/github-ocean/examples/examples.md | 27 ++++++++ .../git/github-ocean/github-ocean.md | 62 ++++++++++++++++++- .../git/github-ocean/gitops/gitops.md | 16 ++++- .../github-ocean/installation/_ci_install.mdx | 10 +-- .../installation/_docker_install.mdx | 4 +- .../installation/_docker_parameters_table.jsx | 6 +- .../installation/_install_methods.mdx | 10 +-- .../installation/_parameters_table.jsx | 6 +- .../installation/installation.mdx | 36 ++++++++++- .../git/github-ocean/migration-guide.md | 55 ++++++++++++++-- 19 files changed, 301 insertions(+), 29 deletions(-) create mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_blueprint.mdx create mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_port_app_config.mdx diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx index e4a7cbac6b..8a43f1c030 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx @@ -1,8 +1,8 @@ | Parameter | Description | Example | Required | | --------- | ----------- | ------- | -------- | -| `OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN` | A GitHub Personal Access Token (PAT) to authenticate with your GitHub Organization. Only required when you're not authenticating as a [Github app](./installation/github-app.mdx) | | ✅ | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN` | A GitHub Personal Access Token (PAT) to authenticate with your GitHub Organization. Use classic PAT for multi-org support (v2.0.0-beta+). Only required when you're not authenticating as a [Github app](./installation/github-app.mdx) | | ✅ | | `OCEAN__INTEGRATION__CONFIG__GTIHUB_HOST` | The API endpoint for your GitHub instance. For GitHub Enterprise Cloud, this will be `https://`. Defaults to `https://api.github.com` if not provided. | | ❌ | -| `OCEAN__INTEGRATION__CONFIG__GTIHUB_ORGANIZATION` | The name of your Github organization | | ✅ | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS` | JSON array of GitHub organization names to sync from (e.g., `["org1","org2"]`). From v2.0.0-beta: classic PAT supports multiple orgs, GitHub App supports only 1 org. Leave empty with classic PAT to sync all accessible organizations. | | ❌ | | `OCEAN__PORT__CLIENT_ID` | Your Port client id([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | | ✅ | | `OCEAN__PORT__CLIENT_SECRET` | Your Port client secret ([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | | ✅ | | `OCEAN__PORT__BASE_URL` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ | diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx index 34dbeead62..ee31417378 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx @@ -1,3 +1,4 @@ +- [`organization`](https://docs.github.com/en/rest/orgs/orgs?apiVersion=2022-11-28#list-organizations-for-the-authenticated-user) - [`repository`](https://docs.github.com/en/rest/repos/repos#get-a-repository) - [`pull-request`](https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request) - [`file`](/build-your-software-catalog/sync-data-to-catalog/git/github/#ingest-files-from-your-repositories) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx index a45dd95779..3a8e7b0c75 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx @@ -17,6 +17,8 @@ resources: readme: file://README.md # fetching the README.md file that is within the root folder of the repository and ingesting its contents as a markdown property url: .html_url defaultBranch: .default_branch + relations: + organization: .__organization.login - kind: pull-request selector: query: "true" # JQ boolean query. If evaluated to false - skip syncing the object. diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx index b61a1b225c..682beec026 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx @@ -27,7 +27,14 @@ }, "mirrorProperties": {}, "calculationProperties": {}, - "relations": {} + "relations": { + "organization": { + "title": "Organization", + "target": "githubOrganization", + "required": false, + "many": false + } + } } ``` 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 cc24964830..59618388f9 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,8 +25,10 @@ resources: query: 'true' files: - path: 'README.md' + organization: my-org # Required from v2.0.0-beta repos: - name: test-repo + branch: main port: entity: mappings: 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 2784966dd5..9cf1600edf 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,6 +8,7 @@ query: 'true' files: - path: '**/package.json' + organization: my-org # Required from v2.0.0-beta 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 d86acc7e8f..10a6c99ed6 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,6 +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 # Required from v2.0.0-beta 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/examples/example-organization/_github_exporter_example_organization_blueprint.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_blueprint.mdx new file mode 100644 index 0000000000..88e17d5451 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_blueprint.mdx @@ -0,0 +1,39 @@ +
+Organization blueprint (click to expand) + +```json showLineNumbers +{ + "identifier": "githubOrganization", + "title": "GitHub Organization", + "icon": "Github", + "schema": { + "properties": { + "url": { + "title": "Organization URL", + "type": "string", + "format": "url" + }, + "description": { + "title": "Description", + "type": "string" + }, + "repositories": { + "title": "Repositories", + "type": "number" + }, + "createdAt": { + "title": "Created At", + "type": "string", + "format": "date-time" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": {} +} +``` + +
+ diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_port_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_port_app_config.mdx new file mode 100644 index 0000000000..30744b05df --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_port_app_config.mdx @@ -0,0 +1,39 @@ +
+ +Port port-app-config.yml (click to expand) + +```yaml showLineNumbers +resources: + - kind: organization + selector: + query: "true" # JQ boolean query. If evaluated to false - skip syncing the object. + port: + entity: + mappings: + identifier: .login + title: .name + blueprint: '"githubOrganization"' + properties: + url: .html_url + description: .description + repositories: .public_repos + createdAt: .created_at + - kind: repository + selector: + query: "true" + port: + entity: + mappings: + identifier: .name + title: .name + blueprint: '"githubRepository"' + properties: + readme: file://README.md + url: .html_url + defaultBranch: .default_branch + relations: + organization: .__organization.login +``` + +
+ diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md index 3fafd4dce8..818579bb45 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md @@ -50,9 +50,36 @@ import DependabotAlertBlueprint from './example-repository-alerts/\_github_expor import CodeScanAlertBlueprint from './example-repository-alerts/\_github_exporter_example_codeScan_alert_blueprint.mdx' import PortRepositoryDependabotAlertMappingAppConfig from './example-repository-alerts/\_github_exporter_example_repo_dependabot_port_app_config.mdx' +import OrganizationBlueprint from './example-organization/\_github_exporter_example_organization_blueprint.mdx' +import OrganizationAppConfig from './example-organization/\_github_exporter_example_organization_port_app_config.mdx' + # Resource mapping examples +## Map organizations and repositories + +:::info Available from v2.0.0-beta +The `organization` kind is available from version `v2.0.0-beta` onwards. +::: + +The following example demonstrates how to ingest your GitHub organizations and their repositories to Port. +You can use the following Port blueprint definitions and `port-app-config.yml`: + + + + + + + +:::tip learn more + +- Port leverages the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to map and transform GitHub objects to Port Entities. +- Click [Here](https://docs.github.com/en/rest/orgs/orgs#get-an-organization) for the GitHub organization object structure. +- Click [Here](https://docs.github.com/en/rest/repos/repos#get-a-repository) for the GitHub repository object structure. + +::: + +After creating the blueprints and committing the `port-app-config.yml` file, you will see new entities in Port matching your organizations and their repositories. The repositories will have a relation to their parent organization. ## Map repositories and pull requests 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 cd0c0dc1fa..b9b685d500 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 @@ -18,6 +18,27 @@ Here's what you can do with the GitHub integration: - Map and organize your desired GitHub resources and their metadata in Port (see supported resources below). - Watch for GitHub object changes (create/update/delete) in real-time, and automatically apply the changes to your software catalog. - Manage Port entities using GitOps. +- **Sync data from multiple GitHub organizations** using a single integration instance. + +### Multi-organization support + +The GitHub integration supports syncing data from multiple GitHub organizations starting from **version 2.0.0-beta**. You can configure which organizations to sync using the `githubOrganizations` configuration parameter. + +:::info Authentication requirements +- **Classic PAT**: Supports multiple organizations. Fine-grained PAT tokens do not support multi-organization authentication. +- **GitHub App**: Only supports a **single organization** (minimum 1, maximum 1). You must specify exactly one organization in the `githubOrganizations` array. +::: + +:::caution Performance impact +Syncing multiple organizations will increase the number of API calls to GitHub and may slow down the integration. The more organizations you sync, the longer the resync time and the higher the API rate limit consumption. Consider syncing only the organizations you need. +::: + +**Configuration options:** +- **With classic PAT**: Specify a list of organizations: `githubOrganizations: ["org1", "org2", "org3"]` +- **With classic PAT**: Leave empty to sync all organizations the PAT user is a member of: `githubOrganizations: []` +- **With GitHub App**: Specify exactly one organization: `githubOrganizations: ["my-org"]` + +When using multi-organization support, the `organization` resource kind is automatically synced, allowing you to model your GitHub organizations in Port. ### Supported resources @@ -136,10 +157,39 @@ resources: Using Port's GitHub integration, you can automatically ingest GitHub resources into Port based on real-time events. -The app allows you to ingest a variety of objects resources provided by the GitHub API, including repositories, pull requests, workflows and more. It also allows you to perform "extract, transform, load (ETL)" on data from the GitHub API into the desired software catalog data model. +The app allows you to ingest a variety of objects resources provided by the GitHub API, including organizations, repositories, pull requests, workflows and more. It also allows you to perform "extract, transform, load (ETL)" on data from the GitHub API into the desired software catalog data model. The GitHub integration uses a YAML configuration file to describe the ETL process to load data into the developer portal. This approach provides a flexible and powerful way to model your Git data without being overly opinionated or complex. +### Ingest organizations + +The GitHub integration can automatically sync organization-level data when using multi-organization support (available from **v2.0.0-beta**). + +Here's an example configuration for the `organization` kind: + +```yaml showLineNumbers +resources: + - kind: organization + selector: + query: 'true' + port: + entity: + mappings: + identifier: .login + title: .name + blueprint: '"githubOrganization"' + properties: + url: .html_url + description: .description + createdAt: .created_at + blog: .blog + location: .location +``` + +:::tip Organization as parent entity +Organizations can serve as parent entities for repositories, teams, and other GitHub resources, helping you model your organizational structure in Port. +::: + ### Ingest files from your repositories Port allows you to fetch `JSON` and `YAML` files from your repositories, and create entities from them in your software catalog. @@ -149,6 +199,10 @@ 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: +:::warning Breaking change in v2.0.0-beta +Starting from version 2.0.0-beta, the `file` kind requires an `organization` field to be specified. This is a breaking change from previous versions. +::: + ```yaml showLineNumbers resources: - kind: file @@ -157,6 +211,7 @@ resources: files: # Note that glob patterns are supported, so you can use wildcards to match multiple files - path: '**/package.json' + organization: my-org # Organization name is required from v2.0.0-beta # The `repos` key can be used to filter the repositories and branch where files should be fetched repos: - name: MyRepo @@ -679,6 +734,7 @@ resources: query: 'true' files: - path: '**/package.json' + organization: my-org # Organization name is required from v2.0.0-beta # Note that in this case we are fetching from a specific repository repos: - name: MyRepo @@ -736,7 +792,11 @@ resources: query: 'true' files: - path: values.yaml + organization: my-org # Organization name is required from v2.0.0-beta skipParsing: true + repos: + - name: MyRepo + branch: main port: entity: mappings: 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 a361050571..987c87a0c0 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 @@ -125,6 +125,10 @@ To edit a mapping configuration: For example, say you want to ingest a `package.json` file form your repository. You can add the following to your GitHub integration mapping: +:::warning Breaking change in v2.0.0-beta +Starting from version 2.0.0-beta, the `file` kind requires an `organization` field to be specified for multi-organization support. +::: + ```yaml resources: ... @@ -133,13 +137,17 @@ resources: query: 'true' files: - path: package.json + organization: my-org # Required from v2.0.0-beta + repos: + - name: my-repo + branch: main port: entity: mappings: - identifier: .file.name + identifier: .path blueprint: '"file"' properties: - content: .file.content + content: .content ``` The `selector.files.path` key also supports glob patterns, so you can ingest multiple files by matching against a pattern and create an entity in Port for each one, for example: @@ -150,6 +158,10 @@ The `selector.files.path` key also supports glob patterns, so you can ingest mul query: 'true' files: - path: 'resources/*.yml' + organization: my-org # Required from v2.0.0-beta + repos: + - name: my-repo + branch: main ``` ### Advantages diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx index a740ab8570..fc8786885f 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx @@ -38,7 +38,7 @@ jobs: config: | githubHost: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_HOST }} githubToken: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN }} - githubOrganization: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION }} + githubOrganizations: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS }} # JSON array format ``` @@ -66,7 +66,7 @@ pipeline { script { withCredentials([ string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_URL', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_URL'), - string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION'), + string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS'), string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN'), string(credentialsId: 'OCEAN__PORT__CLIENT_ID', variable: 'OCEAN__PORT__CLIENT_ID'), string(credentialsId: 'OCEAN__PORT__CLIENT_SECRET', variable: 'OCEAN__PORT__CLIENT_SECRET'), @@ -82,7 +82,7 @@ pipeline { -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_URL=$OCEAN__INTEGRATION__CONFIG__GITHUB_URL \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN \ - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS \ -e OCEAN__PORT__CLIENT_ID=$OCEAN__PORT__CLIENT_ID \ -e OCEAN__PORT__CLIENT_SECRET=$OCEAN__PORT__CLIENT_SECRET \ -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ @@ -129,7 +129,7 @@ steps: -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST=$(OCEAN__INTEGRATION__CONFIG__GITHUB_HOST) \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$(OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN) \ - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$(OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION) \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS=$(OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS) \ -e OCEAN__PORT__CLIENT_ID=$(OCEAN__PORT__CLIENT_ID) \ -e OCEAN__PORT__CLIENT_SECRET=$(OCEAN__PORT__CLIENT_SECRET) \ -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ @@ -174,7 +174,7 @@ ingest_data: -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_URL=$OCEAN__INTEGRATION__CONFIG__GITHUB_URL \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN \ - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS \ -e OCEAN__PORT__CLIENT_ID=$OCEAN__PORT__CLIENT_ID \ -e OCEAN__PORT__CLIENT_SECRET=$OCEAN__PORT__CLIENT_SECRET \ -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_install.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_install.mdx index bb1b264752..baef02adbd 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_install.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_install.mdx @@ -22,7 +22,7 @@ Run the following command to start the app: -e OCEAN__BASE_URL="" \\ #optional, only required if you want to enable live-events -e OCEAN__EVENT_LISTENER__TYPE="POLLING" \\ -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST="" \\ # e.g https://api.github.com - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION="" \\ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS='[""]' \\ # GitHub App supports only 1 org -e OCEAN__INTEGRATION__IDENTIFIER="github-ocean" \\ -e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_ID="" \\ # client id also works -e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_PRIVATE_KEY="" \\ @@ -38,7 +38,7 @@ Run the following command to start the app: -e OCEAN__BASE_URL="" \\ #optional, only required if you want to enable live-events -e OCEAN__EVENT_LISTENER__TYPE="POLLING" \\ -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST="" \\ # e.g https://api.github.com - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION="" \\ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS='["",""]' \\ # Classic PAT supports multiple orgs from v2.0.0-beta -e OCEAN__INTEGRATION__IDENTIFIER="github-ocean" \\ -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN="" \\ -p 8000:8000 \\ diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx index 392a8c3e5b..668b8246cb 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx @@ -45,9 +45,9 @@ export default function DockerParametersTable({ showingApp }) { ❌ - OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION - The GitHub organization the integration was installed in. - ✅ + OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS + JSON array of GitHub organization names to sync data from (e.g., ["org1","org2"]). From v2.0.0-beta, classic PAT supports multiple orgs. GitHub App supports only 1 organization. Leave empty with classic PAT to sync all accessible organizations. + ❌ OCEAN__INTEGRATION__IDENTIFIER diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx index bd27bed59b..d027f3c299 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx @@ -63,7 +63,7 @@ Install the Helm chart: eventListener: type: "POLLING" config: - githubOrganization: "" + githubOrganizations: [""] # GitHub App supports only 1 org githubHost: "" # e.g https://api.github.com githubAppId: "" # app client id also works secrets: @@ -94,7 +94,7 @@ Install the Helm chart: eventListener: type: "POLLING" config: - githubOrganization: "" + githubOrganizations: ["", ""] # From v.2.0.0-beta, classic PAT supports multiple orgs. Leave empty to sync all orgs githubHost: "" # e.g https://api.github.com secrets: githubToken: "" @@ -129,7 +129,9 @@ To install the integration using ArgoCD: 1. Create a `values.yaml` file in `argocd/my-ocean-github-integration` in your git repository with the content: :::note -Be sure to replace the `` and `` placeholders with your actual values. If you are using a self-hosted GitHub instance, update the `githubHost` value to point to your instance. +Be sure to replace the `` and organization placeholders with your actual values. If you are using a self-hosted GitHub instance, update the `githubHost` value to point to your instance. + +For multi-organization support, use a **classic PAT token** and specify multiple organizations in the array. ::: ```yaml showLineNumbers @@ -143,7 +145,7 @@ integration: type: POLLING config: githubHost: https://api.github.com # Or your self-hosted GitHub URL - githubOrganization: "" # your github organization, e.g port-labs + githubOrganizations: ["", ""] # From v.2.0.0, classic PAT supports multiple orgs secrets: githubToken: "" diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx index e0aa056669..1bcc217351 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx @@ -42,9 +42,9 @@ export default function ParametersTable({ showingApp }) { ✅ - integration.config.githubOrganization - The GitHub organization to sync data from. - ✅ + integration.config.githubOrganizations + Array of GitHub organization names to sync data from. For multi-org support, use a classic PAT token. GitHub App supports only 1 organization. Leave empty with classic PAT to sync all accessible organizations. + ❌ integration.config.githubHost diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx index ba2ee8e661..8bbc51e39b 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx @@ -26,9 +26,37 @@ This page outlines the following steps: ## Setup +### Multi-organization support + +Starting from **version 2.0.0-beta**, the GitHub integration supports syncing data from multiple GitHub organizations. + +:::warning Breaking change in v2.0.0-beta +The configuration parameter has changed from `githubOrganization` (singular) to `githubOrganizations` (plural, array format). You must update your configuration when upgrading to v2.0.0-beta. + +**Before:** +```yaml +githubOrganization: "my-org" +``` + +**After (v2.0.0-beta):** +```yaml +githubOrganizations: ["my-org"] # Now an array +``` +::: + +:::info Authentication requirements +- **Classic PAT**: Supports multiple organizations +- **Fine-grained PAT**: Does NOT support multi-organization +- **GitHub App**: Supports exactly **one organization** only +::: + +:::caution Performance impact +Syncing multiple organizations increases API calls and may slow down the integration. Consider syncing only the organizations you need. +::: + ### Create access token -To allow Port to fetch data from your GitHub Organization, you need to create an access token. Port supports two types of tokens for authentication: personal access tokens and GitHub app installation tokens. +To allow Port to fetch data from your GitHub Organization(s), you need to create an access token. Port supports two types of tokens for authentication: personal access tokens and GitHub app installation tokens. @@ -36,7 +64,7 @@ To allow Port to fetch data from your GitHub Organization, you need to create an A Personal Access Token (PAT) is suitable if you're the only one managing the integration and don't need frequent credential rotation. To create a personal access token see Github's [managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). -- The token must belong to a user with access to the relevant Github resources (e.g., repositories, teams). +- The token must belong to a user with access to the relevant Github resources (e.g., repositories, teams) across all organizations you want to sync.
Required permissions @@ -76,6 +104,10 @@ You can reconfigure the permission at any time, giving it access to new reposito A GitHub App provides automatic access token rotation and is a good alternative to PATs. To set it up, see the [GitHub App installation guide](./github-app.mdx). +:::caution Single organization limitation +GitHub App authentication supports **exactly one organization** only. You must specify one organization in the `githubOrganizations` configuration parameter. +::: + diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md index ef6fc815c3..99136210d0 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md @@ -12,12 +12,39 @@ The new Ocean-powered GitHub integration comes with several key improvements: ## Major changes +### Multi-organization support (v2.0.0-beta) + +The GitHub integration now supports ingesting data from multiple GitHub organizations starting from **version 2.0.0-beta**. This is configured using the `githubOrganizations` parameter: + +```yaml showLineNumbers +integration: + config: + githubOrganizations: ["org1", "org2", "org3"] # Classic PAT only +``` + +:::warning Authentication limitations +- **Classic PAT**: Supports multiple organizations. Fine-grained PAT tokens do not support multi-organization authentication. +- **GitHub App**: Only supports a **single organization** (minimum 1, maximum 1). You must specify exactly one organization in the `githubOrganizations` array. +::: + +:::caution Performance impact +Syncing multiple organizations will increase the number of API calls to GitHub and may slow down the integration. The more organizations you sync, the longer the resync time and the higher the API rate limit consumption. Consider syncing only the organizations you need. +::: + +**Configuration by authentication type:** +- **Classic PAT**: If `githubOrganizations` is not provided, the integration will sync all organizations the PAT user is a member of. +- **GitHub App**: Must specify exactly one organization: `githubOrganizations: ["my-org"]` + ### Authentication model #### Personal access token (PAT) You can now authenticate with our GitHub integration using a Personal Access Token (PAT) instead of a GitHub App. This gives you more control over the integration's permissions. For more details, see the [installation page](/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation). +:::info Classic PAT required for multi-org +For multi-organization support, you must use a **classic Personal Access Token**. Fine-grained PAT tokens do not work with multi-organization configurations. +::: + Below is a sample Helm value for this configuration: ```yaml showLineNumbers integration: @@ -29,11 +56,16 @@ integration: If you prefer using a GitHub App, you can still authenticate with our Ocean-powered GitHub integration. You will need to create the app yourself, which is a process similar to our existing self-hosted app installation. This process is [documented here](/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/github-app). +:::caution Single organization limitation +GitHub App authentication only supports **one organization** at a time. You must specify exactly one organization in the `githubOrganizations` array. +::: + Below is a sample Helm value for this configuration: ```yaml showLineNumbers integration: config: githubAppId: "" # app client id also works + githubOrganizations: ["my-org"] # Required: exactly one organization secrets: githubAppPrivateKey: "" ``` @@ -70,6 +102,11 @@ The data blueprints for GitHub have been updated to provide cleaner data structu A key change is how we denote custom attributes. We now add a double underscore prefix (e.g., `__repository`) to attributes that Port adds to the raw API response from GitHub. This makes it clear which fields are part of the original data and which are enrichments from the integration. ### Files & GitOps + +:::warning Breaking change in v2.0.0-beta +Starting from version 2.0.0-beta, the `file` kind requires an `organization` field to be specified. This is a breaking change for multi-organization support. +::: +
Existing configuration (click to expand) @@ -109,6 +146,7 @@ resources: files: # Note that glob patterns are supported, so you can use wildcards to match multiple files - path: '**/package.json' + organization: my-org # ✅ NEW REQUIRED FIELD for multi-organization support from v.2.0.0-beta # The `repos` key can be used to filter the repositories and branch where files should be fetched repos: - name: MyRepo # ✅ new key:value pairs rather than a string. @@ -128,9 +166,10 @@ resources:
Here are the key changes for file mappings: -1. The `repos` selector is now a list of objects, where each object can specify the repository `name` and an optional `branch`. This provides more granular control over which files are fetched. -2. File attributes are no longer nested under a `file` key. They are now at the top level of the data structure. For example, instead of `.file.path`, you should now use `.path`. -3. The `repo` key has been renamed to `repository` when referencing the repository a file belongs to, for consistency with other data kinds. +1. **[BREAKING]** The `organization` field is now **required** for each file pattern. This enables multi-organization support. +2. The `repos` selector is now a list of objects, where each object can specify the repository `name` and an optional `branch`. This provides more granular control over which files are fetched. +3. File attributes are no longer nested under a `file` key. They are now at the top level of the data structure. For example, instead of `.file.path`, you should now use `.path`. +4. The `repo` key has been renamed to `repository` when referencing the repository a file belongs to, for consistency with other data kinds. ### Repository relationships @@ -370,6 +409,10 @@ resources: ### Folders +:::warning Breaking change in v2.0.0-beta +Starting from version 2.0.0-beta, the `folder` kind requires an `organization` field to be specified. This is a breaking change for multi-organization support. +::: + For the `folder` kind, the `folder.name` attribute is no longer part of the response. Instead, you can easily derive the folder name from the `folder.path` using a JQ expression, as shown in the example below:
@@ -408,6 +451,7 @@ resources: query: "true" folders: - path: apps/* + organization: my-org # ✅ NEW REQUIRED FIELD for multi-organization support from v.2.0.0-beta repos: - name: backend-service # ✅ new, now has a 'name' key branch: main # ✅ new, optional branch name @@ -516,7 +560,10 @@ This section provides a high-level summary of the key breaking changes for mappi | Area | Old Value | New Value | Notes | |---|---|---|---| -| **Authentication** | GitHub App Installation | PAT or Self-Created GitHub App | The integration can be authenticated using a Personal Access Token (PAT) or a self-created GitHub App. | +| **Multi-Organization** | N/A | `githubOrganizations` configuration | **[BREAKING in v2.0.0-beta]** New configuration to support multiple organizations. **Classic PAT supports multiple orgs; GitHub App supports exactly 1 org**. Syncing multiple organizations increases API calls and may slow down the integration. | +| **File Organization** | N/A | `organization: "my-org"` | **[BREAKING in v2.0.0-beta]** File patterns now require an `organization` field. | +| **Folder Organization** | N/A | `organization: "my-org"` | **[BREAKING in v2.0.0-beta]** Folder selectors now require an `organization` field. | +| **Authentication** | GitHub App Installation | PAT or Self-Created GitHub App | The integration can be authenticated using a Personal Access Token (PAT) or a self-created GitHub App. **Multi-org requires classic PAT**. | | **Webhooks** | App Webhook | Automatic Setup by Integration | The integration now manages its own webhooks for live events. This requires `webhook` permissions and `liveEvents.baseUrl` to be set. | | **Workflow Runs** | 10 per repository | 100 per workflow | The number of ingested workflow runs has been increased. | | **Repository Type** | N/A | `repositoryType` configuration | A new top-level configuration is available to filter repositories by type (`public`, `private`, or `all`). | From 9e851839a6614228850bdfcb35c61cc39334eff3 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Wed, 15 Oct 2025 01:31:28 +0100 Subject: [PATCH 02/10] fix: update documentation --- .../_github_docker_parameters.mdx | 5 +- .../_file_repo_app_config.mdx | 2 +- .../_package_json_app_config.mdx | 2 +- ...orter_example_monorepo_port_app_config.mdx | 2 +- ...xporter_example_organization_blueprint.mdx | 68 +++++++++++++--- .../git/github-ocean/examples/examples.md | 4 +- .../git/github-ocean/github-ocean.md | 78 +++++++++---------- .../git/github-ocean/gitops/gitops.md | 8 +- .../github-ocean/installation/_ci_install.mdx | 11 ++- .../installation/_docker_install.mdx | 4 +- .../installation/_docker_parameters_table.jsx | 9 ++- .../installation/_install_methods.mdx | 14 ++-- .../installation/_parameters_table.jsx | 9 ++- .../installation/installation.mdx | 29 ++++--- .../git/github-ocean/migration-guide.md | 43 ++++------ 15 files changed, 166 insertions(+), 122 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx index 8a43f1c030..c20504cf80 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx @@ -1,8 +1,9 @@ | Parameter | Description | Example | Required | | --------- | ----------- | ------- | -------- | -| `OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN` | A GitHub Personal Access Token (PAT) to authenticate with your GitHub Organization. Use classic PAT for multi-org support (v2.0.0-beta+). Only required when you're not authenticating as a [Github app](./installation/github-app.mdx) | | ✅ | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN` | A GitHub Personal Access Token (PAT) to authenticate with your GitHub Organization. Use classic PAT for multi-org support (v3.0.0-beta+). Only required when you're not authenticating as a [Github app](./installation/github-app.mdx) | | ✅ | | `OCEAN__INTEGRATION__CONFIG__GTIHUB_HOST` | The API endpoint for your GitHub instance. For GitHub Enterprise Cloud, this will be `https://`. Defaults to `https://api.github.com` if not provided. | | ❌ | -| `OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS` | JSON array of GitHub organization names to sync from (e.g., `["org1","org2"]`). From v2.0.0-beta: classic PAT supports multiple orgs, GitHub App supports only 1 org. Leave empty with classic PAT to sync all accessible organizations. | | ❌ | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION` | The name of your Github organization (for GitHub App or Fine-grained PAT authentication). Required for single-org authentication. | | ❌ | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_MULTI_ORGANIZATIONS` | JSON array of GitHub organization names to sync from (e.g., `["org1","org2"]`). From v3.0.0-beta: classic PAT supports multiple orgs, GitHub App and Fine-grained PAT support only 1 org. Leave empty with classic PAT to sync all accessible organizations. | | ❌ | | `OCEAN__PORT__CLIENT_ID` | Your Port client id([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | | ✅ | | `OCEAN__PORT__CLIENT_SECRET` | Your Port client secret ([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | | ✅ | | `OCEAN__PORT__BASE_URL` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ | 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 59618388f9..6e0bd7872d 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 # Required from v2.0.0-beta + organization: my-org # Required from v3.0.0-beta 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 9cf1600edf..42184c55a0 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 # Required from v2.0.0-beta + organization: my-org # Required from v3.0.0-beta 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 10a6c99ed6..a11c26d3be 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 # Required from v2.0.0-beta + organization: my-org # Required from v3.0.0-beta 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/examples/example-organization/_github_exporter_example_organization_blueprint.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_blueprint.mdx index 88e17d5451..7e73dc4187 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_blueprint.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_blueprint.mdx @@ -4,33 +4,77 @@ ```json showLineNumbers { "identifier": "githubOrganization", - "title": "GitHub Organization", + "description": "This blueprint represents a service in our software catalog", + "title": "Organization", "icon": "Github", "schema": { "properties": { + "login": { + "type": "string", + "title": "Organization Login", + "description": "The GitHub organization login name" + }, + "id": { + "type": "number", + "title": "Organization ID", + "description": "GitHub organization ID" + }, + "nodeId": { + "type": "string", + "title": "Node ID", + "description": "GitHub GraphQL node ID" + }, "url": { - "title": "Organization URL", "type": "string", - "format": "url" + "title": "API URL", + "description": "GitHub API URL for the organization" }, - "description": { - "title": "Description", - "type": "string" + "reposUrl": { + "type": "string", + "title": "Repositories URL", + "description": "URL to organization's repositories" }, - "repositories": { - "title": "Repositories", - "type": "number" + "eventsUrl": { + "type": "string", + "title": "Events URL", + "description": "URL to organization's events" + }, + "hooksUrl": { + "type": "string", + "title": "Webhooks URL", + "description": "URL to organization's webhooks" }, - "createdAt": { - "title": "Created At", + "issuesUrl": { "type": "string", - "format": "date-time" + "title": "Issues URL", + "description": "URL to organization's issues" + }, + "membersUrl": { + "type": "string", + "title": "Members URL", + "description": "URL to organization's members" + }, + "publicMembersUrl": { + "type": "string", + "title": "Public Members URL", + "description": "URL to organization's public members" + }, + "avatarUrl": { + "type": "string", + "title": "Avatar URL", + "description": "Organization avatar image URL" + }, + "description": { + "type": "string", + "title": "Description", + "description": "Organization description" } }, "required": [] }, "mirrorProperties": {}, "calculationProperties": {}, + "aggregationProperties": {}, "relations": {} } ``` diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md index 818579bb45..b6aa58d732 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md @@ -58,8 +58,8 @@ import OrganizationAppConfig from './example-organization/\_github_exporter_exam ## Map organizations and repositories -:::info Available from v2.0.0-beta -The `organization` kind is available from version `v2.0.0-beta` onwards. +:::info Available from v3.0.0-beta +The `organization` kind is available from version `v3.0.0-beta` onwards. ::: The following example demonstrates how to ingest your GitHub organizations and their repositories to 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 b9b685d500..292e252c29 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 @@ -22,23 +22,18 @@ Here's what you can do with the GitHub integration: ### Multi-organization support -The GitHub integration supports syncing data from multiple GitHub organizations starting from **version 2.0.0-beta**. You can configure which organizations to sync using the `githubOrganizations` configuration parameter. +The GitHub integration supports syncing data from multiple GitHub organizations starting from **version 3.0.0-beta**. You can configure which organizations to sync using the `githubOrganization` and `githubMultiOrganizations` configuration parameters. -:::info Authentication requirements -- **Classic PAT**: Supports multiple organizations. Fine-grained PAT tokens do not support multi-organization authentication. -- **GitHub App**: Only supports a **single organization** (minimum 1, maximum 1). You must specify exactly one organization in the `githubOrganizations` array. -::: +:::caution Authentication and configuration requirements: +- **With classic PAT**: + - Specify a list of organizations: `githubMultiOrganizations: ["org1", "org2", "org3"]` + - Leave empty to sync all organizations the PAT user is a member of: `githubMultiOrganizations: []` +- **With GitHub App**: Specify exactly one organization: `githubOrganization: "my-org"` +- **With Fine-grained PAT**: Specify exactly one organization: `githubOrganization: "my-org"` -:::caution Performance impact -Syncing multiple organizations will increase the number of API calls to GitHub and may slow down the integration. The more organizations you sync, the longer the resync time and the higher the API rate limit consumption. Consider syncing only the organizations you need. +**Performance consideration:** Syncing multiple organizations will increase the number of API calls to GitHub and may slow down the integration. The more organizations you sync, the longer the resync time and the higher the API rate limit consumption. Consider syncing only the organizations you need. ::: -**Configuration options:** -- **With classic PAT**: Specify a list of organizations: `githubOrganizations: ["org1", "org2", "org3"]` -- **With classic PAT**: Leave empty to sync all organizations the PAT user is a member of: `githubOrganizations: []` -- **With GitHub App**: Specify exactly one organization: `githubOrganizations: ["my-org"]` - -When using multi-organization support, the `organization` resource kind is automatically synced, allowing you to model your GitHub organizations in Port. ### Supported resources @@ -99,6 +94,28 @@ repositoryType: 'all' deleteDependentEntities: true createMissingRelatedEntities: true resources: + - kind: organization + selector: + query: 'true' + port: + entity: + mappings: + identifier: .login + title: .login + blueprint: '''githubOrganization''' + properties: + login: .login + id: .id + nodeId: .node_id + url: .url + reposUrl: .repos_url + eventsUrl: .events_url + hooksUrl: .hooks_url + issuesUrl: .issues_url + membersUrl: .members_url + publicMembersUrl: .public_members_url + avatarUrl: .avatar_url + description: if .description then .description else "" end - kind: repository selector: query: 'true' @@ -115,6 +132,8 @@ resources: readme: file://README.md url: .html_url language: if .language then .language else "" end + relations: + organization: .owner.login - kind: pull-request selector: query: 'true' @@ -163,28 +182,8 @@ The GitHub integration uses a YAML configuration file to describe the ETL proces ### Ingest organizations -The GitHub integration can automatically sync organization-level data when using multi-organization support (available from **v2.0.0-beta**). - -Here's an example configuration for the `organization` kind: +The GitHub integration can automatically sync organization-level data when using multi-organization support (available from **v3.0.0-beta**). -```yaml showLineNumbers -resources: - - kind: organization - selector: - query: 'true' - port: - entity: - mappings: - identifier: .login - title: .name - blueprint: '"githubOrganization"' - properties: - url: .html_url - description: .description - createdAt: .created_at - blog: .blog - location: .location -``` :::tip Organization as parent entity Organizations can serve as parent entities for repositories, teams, and other GitHub resources, helping you model your organizational structure in Port. @@ -199,8 +198,8 @@ 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: -:::warning Breaking change in v2.0.0-beta -Starting from version 2.0.0-beta, the `file` kind requires an `organization` field to be specified. This is a breaking change from previous versions. +:::warning Breaking change in v3.0.0-beta +Starting from version 3.0.0-beta, the `file` kind requires an `organization` field to be specified. This is a breaking change from previous versions. ::: ```yaml showLineNumbers @@ -211,7 +210,7 @@ resources: files: # Note that glob patterns are supported, so you can use wildcards to match multiple files - path: '**/package.json' - organization: my-org # Organization name is required from v2.0.0-beta + organization: my-org # Organization name is required from v3.0.0-beta # The `repos` key can be used to filter the repositories and branch where files should be fetched repos: - name: MyRepo @@ -705,6 +704,7 @@ In any case, the structure of the available data looks like this: "network_count": 33404, "subscribers_count": 1 }, + "organization": "Test-Org", "branch": "main", "path": "build/package.json", "name": "package.json", @@ -734,7 +734,7 @@ resources: query: 'true' files: - path: '**/package.json' - organization: my-org # Organization name is required from v2.0.0-beta + organization: my-org # Organization name is required from v3.0.0-beta # Note that in this case we are fetching from a specific repository repos: - name: MyRepo @@ -792,7 +792,7 @@ resources: query: 'true' files: - path: values.yaml - organization: my-org # Organization name is required from v2.0.0-beta + organization: my-org # Organization name is required from v3.0.0-beta skipParsing: true 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 987c87a0c0..66b0893958 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 @@ -125,8 +125,8 @@ To edit a mapping configuration: For example, say you want to ingest a `package.json` file form your repository. You can add the following to your GitHub integration mapping: -:::warning Breaking change in v2.0.0-beta -Starting from version 2.0.0-beta, the `file` kind requires an `organization` field to be specified for multi-organization support. +:::warning Breaking change in v3.0.0-beta +Starting from version 3.0.0-beta, the `file` kind requires an `organization` field to be specified for multi-organization support. ::: ```yaml @@ -137,7 +137,7 @@ resources: query: 'true' files: - path: package.json - organization: my-org # Required from v2.0.0-beta + organization: my-org # Required from v3.0.0-beta repos: - name: my-repo branch: main @@ -158,7 +158,7 @@ The `selector.files.path` key also supports glob patterns, so you can ingest mul query: 'true' files: - path: 'resources/*.yml' - organization: my-org # Required from v2.0.0-beta + organization: my-org # Required from v3.0.0-beta repos: - name: my-repo branch: main diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx index fc8786885f..6125669640 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx @@ -38,7 +38,7 @@ jobs: config: | githubHost: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_HOST }} githubToken: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN }} - githubOrganizations: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS }} # JSON array format + githubOrganization: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION }} ``` @@ -66,8 +66,7 @@ pipeline { script { withCredentials([ string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_URL', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_URL'), - string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS'), - string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN'), + string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION'), string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN'), string(credentialsId: 'OCEAN__PORT__CLIENT_ID', variable: 'OCEAN__PORT__CLIENT_ID'), string(credentialsId: 'OCEAN__PORT__CLIENT_SECRET', variable: 'OCEAN__PORT__CLIENT_SECRET'), ]) { @@ -82,7 +81,7 @@ pipeline { -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_URL=$OCEAN__INTEGRATION__CONFIG__GITHUB_URL \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN \ - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION \ -e OCEAN__PORT__CLIENT_ID=$OCEAN__PORT__CLIENT_ID \ -e OCEAN__PORT__CLIENT_SECRET=$OCEAN__PORT__CLIENT_SECRET \ -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ @@ -129,7 +128,7 @@ steps: -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST=$(OCEAN__INTEGRATION__CONFIG__GITHUB_HOST) \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$(OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN) \ - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS=$(OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS) \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$(OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION) \ -e OCEAN__PORT__CLIENT_ID=$(OCEAN__PORT__CLIENT_ID) \ -e OCEAN__PORT__CLIENT_SECRET=$(OCEAN__PORT__CLIENT_SECRET) \ -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ @@ -174,7 +173,7 @@ ingest_data: -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_URL=$OCEAN__INTEGRATION__CONFIG__GITHUB_URL \ -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN \ - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION \ -e OCEAN__PORT__CLIENT_ID=$OCEAN__PORT__CLIENT_ID \ -e OCEAN__PORT__CLIENT_SECRET=$OCEAN__PORT__CLIENT_SECRET \ -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_install.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_install.mdx index baef02adbd..bb1b264752 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_install.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_install.mdx @@ -22,7 +22,7 @@ Run the following command to start the app: -e OCEAN__BASE_URL="" \\ #optional, only required if you want to enable live-events -e OCEAN__EVENT_LISTENER__TYPE="POLLING" \\ -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST="" \\ # e.g https://api.github.com - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS='[""]' \\ # GitHub App supports only 1 org + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION="" \\ -e OCEAN__INTEGRATION__IDENTIFIER="github-ocean" \\ -e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_ID="" \\ # client id also works -e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_PRIVATE_KEY="" \\ @@ -38,7 +38,7 @@ Run the following command to start the app: -e OCEAN__BASE_URL="" \\ #optional, only required if you want to enable live-events -e OCEAN__EVENT_LISTENER__TYPE="POLLING" \\ -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST="" \\ # e.g https://api.github.com - -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS='["",""]' \\ # Classic PAT supports multiple orgs from v2.0.0-beta + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION="" \\ -e OCEAN__INTEGRATION__IDENTIFIER="github-ocean" \\ -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN="" \\ -p 8000:8000 \\ diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx index 668b8246cb..081fcd9ed6 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx @@ -45,8 +45,13 @@ export default function DockerParametersTable({ showingApp }) { ❌ - OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONS - JSON array of GitHub organization names to sync data from (e.g., ["org1","org2"]). From v2.0.0-beta, classic PAT supports multiple orgs. GitHub App supports only 1 organization. Leave empty with classic PAT to sync all accessible organizations. + OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION + Single GitHub organization name to sync data from (for GitHub App or Fine-grained PAT). Required for single-org authentication. + ❌ + + + OCEAN__INTEGRATION__CONFIG__GITHUB_MULTI_ORGANIZATIONS + JSON array of GitHub organization names to sync data from (e.g., ["org1","org2"]). From v3.0.0-beta, classic PAT supports multiple orgs. Leave empty with classic PAT to sync all accessible organizations. ❌ diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx index d027f3c299..75270c436a 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx @@ -63,7 +63,7 @@ Install the Helm chart: eventListener: type: "POLLING" config: - githubOrganizations: [""] # GitHub App supports only 1 org + githubOrganization: "" githubHost: "" # e.g https://api.github.com githubAppId: "" # app client id also works secrets: @@ -94,7 +94,7 @@ Install the Helm chart: eventListener: type: "POLLING" config: - githubOrganizations: ["", ""] # From v.2.0.0-beta, classic PAT supports multiple orgs. Leave empty to sync all orgs + githubOrganization: "" githubHost: "" # e.g https://api.github.com secrets: githubToken: "" @@ -129,9 +129,13 @@ To install the integration using ArgoCD: 1. Create a `values.yaml` file in `argocd/my-ocean-github-integration` in your git repository with the content: :::note -Be sure to replace the `` and organization placeholders with your actual values. If you are using a self-hosted GitHub instance, update the `githubHost` value to point to your instance. +Be sure to replace the `` and `` placeholders with your actual values. If you are using a self-hosted GitHub instance, update the `githubHost` value to point to your instance. -For multi-organization support, use a **classic PAT token** and specify multiple organizations in the array. +For multi-organization support, use a **classic PAT token** and specify multiple organizations in the array + +```yaml +githubMultiOrganizations: ["org1", "org2", "org3"] # Array format +``` ::: ```yaml showLineNumbers @@ -145,7 +149,7 @@ integration: type: POLLING config: githubHost: https://api.github.com # Or your self-hosted GitHub URL - githubOrganizations: ["", ""] # From v.2.0.0, classic PAT supports multiple orgs + githubOrganization: "" # your github organization, e.g port-labs secrets: githubToken: "" diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx index 1bcc217351..052cf81e3c 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx @@ -42,8 +42,13 @@ export default function ParametersTable({ showingApp }) { ✅ - integration.config.githubOrganizations - Array of GitHub organization names to sync data from. For multi-org support, use a classic PAT token. GitHub App supports only 1 organization. Leave empty with classic PAT to sync all accessible organizations. + integration.config.githubOrganization + Single GitHub organization name to sync data from (for GitHub App or Fine-grained PAT). Required for single-org authentication. + ❌ + + + integration.config.githubMultiOrganizations + Array of GitHub organization names to sync data from (for Classic PAT). For multi-org support, use a classic PAT token. Leave empty with classic PAT to sync all accessible organizations. ❌ diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx index 8bbc51e39b..d85eb764df 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx @@ -28,30 +28,27 @@ This page outlines the following steps: ### Multi-organization support -Starting from **version 2.0.0-beta**, the GitHub integration supports syncing data from multiple GitHub organizations. +Starting from **version 3.0.0-beta**, the GitHub integration supports syncing data from multiple GitHub organizations. -:::warning Breaking change in v2.0.0-beta -The configuration parameter has changed from `githubOrganization` (singular) to `githubOrganizations` (plural, array format). You must update your configuration when upgrading to v2.0.0-beta. +:::warning Breaking change in v3.0.0-beta +The configuration parameters have changed to support different authentication types: -**Before:** +**For Classic PAT (multiple organizations):** ```yaml -githubOrganization: "my-org" +githubMultiOrganizations: ["org1", "org2", "org3"] # Array format ``` -**After (v2.0.0-beta):** +**For GitHub App or Fine-grained PAT (single organization):** ```yaml -githubOrganizations: ["my-org"] # Now an array +githubOrganization: "my-org" # String format ``` -::: -:::info Authentication requirements -- **Classic PAT**: Supports multiple organizations -- **Fine-grained PAT**: Does NOT support multi-organization -- **GitHub App**: Supports exactly **one organization** only -::: +**Authentication requirements:** +- **Classic PAT**: Supports multiple organizations using `githubMultiOrganizations` +- **Fine-grained PAT**: Supports exactly **one organization** using `githubOrganization` +- **GitHub App**: Supports exactly **one organization** using `githubOrganization` -:::caution Performance impact -Syncing multiple organizations increases API calls and may slow down the integration. Consider syncing only the organizations you need. +**Performance consideration:** Syncing multiple organizations increases API calls and may slow down the integration. Consider syncing only the organizations you need. ::: ### Create access token @@ -105,7 +102,7 @@ A GitHub App provides automatic access token rotation and is a good alternative To set it up, see the [GitHub App installation guide](./github-app.mdx). :::caution Single organization limitation -GitHub App authentication supports **exactly one organization** only. You must specify one organization in the `githubOrganizations` configuration parameter. +GitHub App authentication supports **exactly one organization** only. You must specify one organization using the `githubOrganization` configuration parameter. ::: diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md index 99136210d0..e3b9c5b521 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md @@ -12,29 +12,18 @@ The new Ocean-powered GitHub integration comes with several key improvements: ## Major changes -### Multi-organization support (v2.0.0-beta) +### Multi-organization support (v3.0.0-beta) -The GitHub integration now supports ingesting data from multiple GitHub organizations starting from **version 2.0.0-beta**. This is configured using the `githubOrganizations` parameter: +The GitHub integration now supports ingesting data from multiple GitHub organizations starting from **version 3.0.0-beta**. This is configured using the `githubOrganization` and `githubMultiOrganizations` parameters: ```yaml showLineNumbers integration: config: - githubOrganizations: ["org1", "org2", "org3"] # Classic PAT only + githubMultiOrganizations: ["org1", "org2", "org3"] # Classic PAT only + # OR + githubOrganization: "my-org" # GitHub App or Fine-grained PAT only ``` -:::warning Authentication limitations -- **Classic PAT**: Supports multiple organizations. Fine-grained PAT tokens do not support multi-organization authentication. -- **GitHub App**: Only supports a **single organization** (minimum 1, maximum 1). You must specify exactly one organization in the `githubOrganizations` array. -::: - -:::caution Performance impact -Syncing multiple organizations will increase the number of API calls to GitHub and may slow down the integration. The more organizations you sync, the longer the resync time and the higher the API rate limit consumption. Consider syncing only the organizations you need. -::: - -**Configuration by authentication type:** -- **Classic PAT**: If `githubOrganizations` is not provided, the integration will sync all organizations the PAT user is a member of. -- **GitHub App**: Must specify exactly one organization: `githubOrganizations: ["my-org"]` - ### Authentication model #### Personal access token (PAT) @@ -57,7 +46,7 @@ integration: If you prefer using a GitHub App, you can still authenticate with our Ocean-powered GitHub integration. You will need to create the app yourself, which is a process similar to our existing self-hosted app installation. This process is [documented here](/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/github-app). :::caution Single organization limitation -GitHub App authentication only supports **one organization** at a time. You must specify exactly one organization in the `githubOrganizations` array. +GitHub App authentication only supports **one organization** at a time. You must specify exactly one organization using `githubOrganization`. ::: Below is a sample Helm value for this configuration: @@ -65,7 +54,7 @@ Below is a sample Helm value for this configuration: integration: config: githubAppId: "" # app client id also works - githubOrganizations: ["my-org"] # Required: exactly one organization + githubOrganization: "my-org" # Required for single organization support regardlass of token type secrets: githubAppPrivateKey: "" ``` @@ -103,8 +92,8 @@ A key change is how we denote custom attributes. We now add a double underscore ### Files & GitOps -:::warning Breaking change in v2.0.0-beta -Starting from version 2.0.0-beta, the `file` kind requires an `organization` field to be specified. This is a breaking change for multi-organization support. +:::warning Breaking change in v3.0.0-beta +Starting from version 3.0.0-beta, the `file` kind requires an `organization` field to be specified. This is a breaking change for multi-organization support. :::
@@ -146,7 +135,7 @@ resources: files: # Note that glob patterns are supported, so you can use wildcards to match multiple files - path: '**/package.json' - organization: my-org # ✅ NEW REQUIRED FIELD for multi-organization support from v.2.0.0-beta + organization: my-org # ✅ NEW REQUIRED FIELD for multi-organization support from v.3.0.0-beta # The `repos` key can be used to filter the repositories and branch where files should be fetched repos: - name: MyRepo # ✅ new key:value pairs rather than a string. @@ -409,8 +398,8 @@ resources: ### Folders -:::warning Breaking change in v2.0.0-beta -Starting from version 2.0.0-beta, the `folder` kind requires an `organization` field to be specified. This is a breaking change for multi-organization support. +:::warning Breaking change in v3.0.0-beta +Starting from version 3.0.0-beta, the `folder` kind requires an `organization` field to be specified. This is a breaking change for multi-organization support. ::: For the `folder` kind, the `folder.name` attribute is no longer part of the response. Instead, you can easily derive the folder name from the `folder.path` using a JQ expression, as shown in the example below: @@ -451,7 +440,7 @@ resources: query: "true" folders: - path: apps/* - organization: my-org # ✅ NEW REQUIRED FIELD for multi-organization support from v.2.0.0-beta + organization: my-org # ✅ NEW REQUIRED FIELD for multi-organization support from v.3.0.0-beta repos: - name: backend-service # ✅ new, now has a 'name' key branch: main # ✅ new, optional branch name @@ -560,9 +549,9 @@ This section provides a high-level summary of the key breaking changes for mappi | Area | Old Value | New Value | Notes | |---|---|---|---| -| **Multi-Organization** | N/A | `githubOrganizations` configuration | **[BREAKING in v2.0.0-beta]** New configuration to support multiple organizations. **Classic PAT supports multiple orgs; GitHub App supports exactly 1 org**. Syncing multiple organizations increases API calls and may slow down the integration. | -| **File Organization** | N/A | `organization: "my-org"` | **[BREAKING in v2.0.0-beta]** File patterns now require an `organization` field. | -| **Folder Organization** | N/A | `organization: "my-org"` | **[BREAKING in v2.0.0-beta]** Folder selectors now require an `organization` field. | +| **Multi-Organization** | N/A | `githubOrganization` and `githubMultiOrganizations` configuration | New configuration to support multiple organizations. **Classic PAT supports multiple orgs using `githubMultiOrganizations`; GitHub App and Fine-grained PAT support exactly 1 org using `githubOrganization`**. Syncing multiple organizations increases API calls and may slow down the integration. | +| **File Organization** | N/A | `organization: "my-org"` | **[BREAKING in v3.0.0-beta]** File patterns now require an `organization` field. | +| **Folder Organization** | N/A | `organization: "my-org"` | **[BREAKING in v3.0.0-beta]** Folder selectors now require an `organization` field. | | **Authentication** | GitHub App Installation | PAT or Self-Created GitHub App | The integration can be authenticated using a Personal Access Token (PAT) or a self-created GitHub App. **Multi-org requires classic PAT**. | | **Webhooks** | App Webhook | Automatic Setup by Integration | The integration now manages its own webhooks for live events. This requires `webhook` permissions and `liveEvents.baseUrl` to be set. | | **Workflow Runs** | 10 per repository | 100 per workflow | The number of ingested workflow runs has been increased. | From 87ec598c06e3da55ef529262b16e851287731823 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Wed, 15 Oct 2025 14:05:55 +0100 Subject: [PATCH 03/10] fix: attend to review comments --- .../git/github-ocean/installation/_ci_install.mdx | 3 ++- .../git/github-ocean/installation/_install_methods.mdx | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx index 6125669640..a740ab8570 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_ci_install.mdx @@ -66,7 +66,8 @@ pipeline { script { withCredentials([ string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_URL', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_URL'), - string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION'), string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN'), + string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION'), + string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN'), string(credentialsId: 'OCEAN__PORT__CLIENT_ID', variable: 'OCEAN__PORT__CLIENT_ID'), string(credentialsId: 'OCEAN__PORT__CLIENT_SECRET', variable: 'OCEAN__PORT__CLIENT_SECRET'), ]) { diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx index 75270c436a..76424679bf 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx @@ -128,7 +128,7 @@ To install the integration using ArgoCD: 1. Create a `values.yaml` file in `argocd/my-ocean-github-integration` in your git repository with the content: -:::note +:::info Placeholder Replacement Required Be sure to replace the `` and `` placeholders with your actual values. If you are using a self-hosted GitHub instance, update the `githubHost` value to point to your instance. For multi-organization support, use a **classic PAT token** and specify multiple organizations in the array From ec9ae60bbf38106c7db244c499ed97c44e3b4859 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Thu, 16 Oct 2025 16:36:05 +0100 Subject: [PATCH 04/10] fix: update docs with no breaking changes --- .../_file_repo_app_config.mdx | 2 +- .../_package_json_app_config.mdx | 2 +- ...orter_example_monorepo_port_app_config.mdx | 2 +- .../git/github-ocean/github-ocean.md | 13 ++++------ .../git/github-ocean/gitops/gitops.md | 8 +++---- .../installation/installation.mdx | 24 ++++--------------- .../git/github-ocean/migration-guide.md | 20 ++++++++-------- 7 files changed, 27 insertions(+), 44 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 6e0bd7872d..134a4a785f 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 # Required from v3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org 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 42184c55a0..dc3332e2fa 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 # Required from v3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org 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 a11c26d3be..517264d5a4 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 # Required from v3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org 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 292e252c29..32ec7da210 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 @@ -198,8 +198,8 @@ 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: -:::warning Breaking change in v3.0.0-beta -Starting from version 3.0.0-beta, the `file` kind requires an `organization` field to be specified. This is a breaking change from previous versions. +:::info Organization field in file selectors +The `organization` field is optional if `githubOrganization` is set globally. It is required when no global organization is provided (e.g., Classic PAT syncing multiple orgs). ::: ```yaml showLineNumbers @@ -210,7 +210,7 @@ resources: files: # Note that glob patterns are supported, so you can use wildcards to match multiple files - path: '**/package.json' - organization: my-org # Organization name is required from v3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org # The `repos` key can be used to filter the repositories and branch where files should be fetched repos: - name: MyRepo @@ -734,7 +734,7 @@ resources: query: 'true' files: - path: '**/package.json' - organization: my-org # Organization name is required from v3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org # Note that in this case we are fetching from a specific repository repos: - name: MyRepo @@ -755,9 +755,6 @@ resources: relations: {} ``` -The `itemsToParse` key is used to specify the path to the array of items you want to parse from the file. In this case, we are parsing the `dependencies` array from the `package.json` file. -Once the array is parsed, we can use the `item` key to refer to each item in the array. - #### Multi-document YAML files For multi-document YAML files (a single file containing multiple YAML documents separated by `---`), `.content` will not resolve to an object, but to an array of objects. @@ -792,7 +789,7 @@ resources: query: 'true' files: - path: values.yaml - organization: my-org # Organization name is required from v3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org skipParsing: true 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 66b0893958..265c39be63 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 @@ -125,8 +125,8 @@ To edit a mapping configuration: For example, say you want to ingest a `package.json` file form your repository. You can add the following to your GitHub integration mapping: -:::warning Breaking change in v3.0.0-beta -Starting from version 3.0.0-beta, the `file` kind requires an `organization` field to be specified for multi-organization support. +:::info Organization field for file selectors +Optional if `githubOrganization` is set; required only when no global org is provided. ::: ```yaml @@ -137,7 +137,7 @@ resources: query: 'true' files: - path: package.json - organization: my-org # Required from v3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org repos: - name: my-repo branch: main @@ -158,7 +158,7 @@ The `selector.files.path` key also supports glob patterns, so you can ingest mul query: 'true' files: - path: 'resources/*.yml' - organization: my-org # Required from v3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org repos: - name: my-repo branch: main diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx index d85eb764df..f73669b8b7 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx @@ -30,25 +30,11 @@ This page outlines the following steps: Starting from **version 3.0.0-beta**, the GitHub integration supports syncing data from multiple GitHub organizations. -:::warning Breaking change in v3.0.0-beta -The configuration parameters have changed to support different authentication types: - -**For Classic PAT (multiple organizations):** -```yaml -githubMultiOrganizations: ["org1", "org2", "org3"] # Array format -``` - -**For GitHub App or Fine-grained PAT (single organization):** -```yaml -githubOrganization: "my-org" # String format -``` - -**Authentication requirements:** -- **Classic PAT**: Supports multiple organizations using `githubMultiOrganizations` -- **Fine-grained PAT**: Supports exactly **one organization** using `githubOrganization` -- **GitHub App**: Supports exactly **one organization** using `githubOrganization` - -**Performance consideration:** Syncing multiple organizations increases API calls and may slow down the integration. Consider syncing only the organizations you need. +:::info Multi-organization configuration +- Classic PAT: optional `githubMultiOrganizations: ["org1", "org2", "org3"]`. If omitted, all accessible orgs are synced. +- GitHub App and fine-grained PAT: use a single `githubOrganization`. +- Do not set both `githubOrganization` and `githubMultiOrganizations` at the same time. +- Performance: syncing multiple organizations increases API calls and may slow down the integration. ::: ### Create access token diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md index e3b9c5b521..de2e044d19 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md @@ -92,8 +92,8 @@ A key change is how we denote custom attributes. We now add a double underscore ### Files & GitOps -:::warning Breaking change in v3.0.0-beta -Starting from version 3.0.0-beta, the `file` kind requires an `organization` field to be specified. This is a breaking change for multi-organization support. +:::info Organization field in file selectors +The `organization` field is optional if `githubOrganization` is set globally. It is required when no global organization is provided (e.g., Classic PAT syncing multiple orgs). :::
@@ -135,7 +135,7 @@ resources: files: # Note that glob patterns are supported, so you can use wildcards to match multiple files - path: '**/package.json' - organization: my-org # ✅ NEW REQUIRED FIELD for multi-organization support from v.3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org # The `repos` key can be used to filter the repositories and branch where files should be fetched repos: - name: MyRepo # ✅ new key:value pairs rather than a string. @@ -155,7 +155,7 @@ resources:
Here are the key changes for file mappings: -1. **[BREAKING]** The `organization` field is now **required** for each file pattern. This enables multi-organization support. +1. The `organization` field can be specified per file pattern when no global organization is configured. 2. The `repos` selector is now a list of objects, where each object can specify the repository `name` and an optional `branch`. This provides more granular control over which files are fetched. 3. File attributes are no longer nested under a `file` key. They are now at the top level of the data structure. For example, instead of `.file.path`, you should now use `.path`. 4. The `repo` key has been renamed to `repository` when referencing the repository a file belongs to, for consistency with other data kinds. @@ -398,8 +398,8 @@ resources: ### Folders -:::warning Breaking change in v3.0.0-beta -Starting from version 3.0.0-beta, the `folder` kind requires an `organization` field to be specified. This is a breaking change for multi-organization support. +:::info Organization field in folder selectors +The `organization` field is optional if `githubOrganization` is set globally. It is required when no global organization is provided (e.g., Classic PAT syncing multiple orgs). ::: For the `folder` kind, the `folder.name` attribute is no longer part of the response. Instead, you can easily derive the folder name from the `folder.path` using a JQ expression, as shown in the example below: @@ -440,7 +440,7 @@ resources: query: "true" folders: - path: apps/* - organization: my-org # ✅ NEW REQUIRED FIELD for multi-organization support from v.3.0.0-beta + organization: my-org # Optional if githubOrganization is set; required if no global org repos: - name: backend-service # ✅ new, now has a 'name' key branch: main # ✅ new, optional branch name @@ -545,13 +545,13 @@ resources: ## Summary of key changes -This section provides a high-level summary of the key breaking changes for mappings. +This section provides a high-level summary of the key changes for mappings. | Area | Old Value | New Value | Notes | |---|---|---|---| | **Multi-Organization** | N/A | `githubOrganization` and `githubMultiOrganizations` configuration | New configuration to support multiple organizations. **Classic PAT supports multiple orgs using `githubMultiOrganizations`; GitHub App and Fine-grained PAT support exactly 1 org using `githubOrganization`**. Syncing multiple organizations increases API calls and may slow down the integration. | -| **File Organization** | N/A | `organization: "my-org"` | **[BREAKING in v3.0.0-beta]** File patterns now require an `organization` field. | -| **Folder Organization** | N/A | `organization: "my-org"` | **[BREAKING in v3.0.0-beta]** Folder selectors now require an `organization` field. | +| **File Organization** | N/A | `organization: "my-org"` | Optional if `githubOrganization` is set; required when no global org (e.g., Classic PAT multi-org). | +| **Folder Organization** | N/A | `organization: "my-org"` | Optional if `githubOrganization` is set; required when no global org (e.g., Classic PAT multi-org). | | **Authentication** | GitHub App Installation | PAT or Self-Created GitHub App | The integration can be authenticated using a Personal Access Token (PAT) or a self-created GitHub App. **Multi-org requires classic PAT**. | | **Webhooks** | App Webhook | Automatic Setup by Integration | The integration now manages its own webhooks for live events. This requires `webhook` permissions and `liveEvents.baseUrl` to be set. | | **Workflow Runs** | 10 per repository | 100 per workflow | The number of ingested workflow runs has been increased. | From 8f3ee8c224a781f3a909ab3ba641bbad3974ce59 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Mon, 20 Oct 2025 10:29:30 +0100 Subject: [PATCH 05/10] fix: update docs --- .../_github_docker_parameters.mdx | 1 - .../_file_repo_app_config.mdx | 2 +- .../_package_json_app_config.mdx | 2 +- ...orter_example_monorepo_port_app_config.mdx | 2 +- .../git/github-ocean/github-ocean.md | 32 ++++++++++++----- .../git/github-ocean/gitops/gitops.md | 6 ++-- .../installation/_docker_parameters_table.jsx | 7 +--- .../installation/_install_methods.mdx | 12 +++++-- .../installation/_parameters_table.jsx | 6 +--- .../installation/installation.mdx | 6 ++-- .../git/github-ocean/migration-guide.md | 34 +++++++++---------- 11 files changed, 59 insertions(+), 51 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx index c20504cf80..ac33d71ff1 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx @@ -3,7 +3,6 @@ | `OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN` | A GitHub Personal Access Token (PAT) to authenticate with your GitHub Organization. Use classic PAT for multi-org support (v3.0.0-beta+). Only required when you're not authenticating as a [Github app](./installation/github-app.mdx) | | ✅ | | `OCEAN__INTEGRATION__CONFIG__GTIHUB_HOST` | The API endpoint for your GitHub instance. For GitHub Enterprise Cloud, this will be `https://`. Defaults to `https://api.github.com` if not provided. | | ❌ | | `OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION` | The name of your Github organization (for GitHub App or Fine-grained PAT authentication). Required for single-org authentication. | | ❌ | -| `OCEAN__INTEGRATION__CONFIG__GITHUB_MULTI_ORGANIZATIONS` | JSON array of GitHub organization names to sync from (e.g., `["org1","org2"]`). From v3.0.0-beta: classic PAT supports multiple orgs, GitHub App and Fine-grained PAT support only 1 org. Leave empty with classic PAT to sync all accessible organizations. | | ❌ | | `OCEAN__PORT__CLIENT_ID` | Your Port client id([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | | ✅ | | `OCEAN__PORT__CLIENT_SECRET` | Your Port client secret ([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | | ✅ | | `OCEAN__PORT__BASE_URL` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ | 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 134a4a785f..00836c1085 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 no global org + organization: my-org # Optional if githubOrganization is set; required if not set 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 dc3332e2fa..016d13224a 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 no global org + 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 517264d5a4..853c1d946f 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 no global org + 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 32ec7da210..82632af97f 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 @@ -22,12 +22,26 @@ Here's what you can do with the GitHub integration: ### Multi-organization support -The GitHub integration supports syncing data from multiple GitHub organizations starting from **version 3.0.0-beta**. You can configure which organizations to sync using the `githubOrganization` and `githubMultiOrganizations` configuration parameters. +The GitHub integration supports syncing data from multiple GitHub organizations starting from **version 3.0.0-beta**. You can configure which organizations to sync using a single-org `githubOrganization`, or by listing organizations in your Port mapping (`organizations`). + +
+Mapping multi organizations (Click to expand) + +```yaml showLineNumbers +deleteDependentEntities: true +createMissingRelatedEntities: true +enableMergeEntity: true +organizations: + - org1 + - org2 +# ... rest of your mapping (repositoryType, resources, etc.) ... +``` +
+ :::caution Authentication and configuration requirements: - **With classic PAT**: - - Specify a list of organizations: `githubMultiOrganizations: ["org1", "org2", "org3"]` - - Leave empty to sync all organizations the PAT user is a member of: `githubMultiOrganizations: []` + - Specify organizations in PortMapping: `organizations: ["org1", "org2", "org3"]` - **With GitHub App**: Specify exactly one organization: `githubOrganization: "my-org"` - **With Fine-grained PAT**: Specify exactly one organization: `githubOrganization: "my-org"` @@ -182,11 +196,11 @@ The GitHub integration uses a YAML configuration file to describe the ETL proces ### Ingest organizations -The GitHub integration can automatically sync organization-level data when using multi-organization support (available from **v3.0.0-beta**). +The GitHub integration automatically syncs organization-level data (available from **v3.0.0-beta**). :::tip Organization as parent entity -Organizations can serve as parent entities for repositories, teams, and other GitHub resources, helping you model your organizational structure in Port. +Organizations serve as parent entities for repositories, teams, and other GitHub resources, helping you model your organizational structure in Port. ::: ### Ingest files from your repositories @@ -199,7 +213,7 @@ 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 if `githubOrganization` is set globally. It is required when no global organization is provided (e.g., Classic PAT syncing multiple orgs). +The `organization` field is optional when `githubOrganization` is set in the deployment config. It is required when no deployment-level organization is provided (e.g., Classic PAT with multiple organizations defined in your Port mapping). ::: ```yaml showLineNumbers @@ -210,7 +224,7 @@ 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 no global org + 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 repos: - name: MyRepo @@ -734,7 +748,7 @@ resources: query: 'true' files: - path: '**/package.json' - organization: my-org # Optional if githubOrganization is set; required if no global org + organization: my-org # Optional if githubOrganization is set; required if not set # Note that in this case we are fetching from a specific repository repos: - name: MyRepo @@ -789,7 +803,7 @@ resources: query: 'true' files: - path: values.yaml - organization: my-org # Optional if githubOrganization is set; required if no global org + organization: my-org # Optional if githubOrganization is set; required if not set skipParsing: true 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 265c39be63..e980e5dc61 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 @@ -126,7 +126,7 @@ To edit a mapping configuration: For example, say you want to ingest a `package.json` file form your repository. You can add the following to your GitHub integration mapping: :::info Organization field for file selectors -Optional if `githubOrganization` is set; required only when no global org is provided. +Optional if `githubOrganization` is set; required only when not set. ::: ```yaml @@ -137,7 +137,7 @@ resources: query: 'true' files: - path: package.json - organization: my-org # Optional if githubOrganization is set; required if no global org + organization: my-org # Optional if githubOrganization is set; required if not set repos: - name: my-repo branch: main @@ -158,7 +158,7 @@ The `selector.files.path` key also supports glob patterns, so you can ingest mul query: 'true' files: - path: 'resources/*.yml' - organization: my-org # Optional if githubOrganization is set; required if no global org + organization: my-org # Optional if githubOrganization is set; required if not set repos: - name: my-repo branch: main diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx index 081fcd9ed6..7a16878546 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_docker_parameters_table.jsx @@ -46,14 +46,9 @@ export default function DockerParametersTable({ showingApp }) { OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION - Single GitHub organization name to sync data from (for GitHub App or Fine-grained PAT). Required for single-org authentication. + Single GitHub organization name to sync data from a single organization. Required for single-org authentication. ❌ - - OCEAN__INTEGRATION__CONFIG__GITHUB_MULTI_ORGANIZATIONS - JSON array of GitHub organization names to sync data from (e.g., ["org1","org2"]). From v3.0.0-beta, classic PAT supports multiple orgs. Leave empty with classic PAT to sync all accessible organizations. - ❌ - OCEAN__INTEGRATION__IDENTIFIER A unique identifier for the integration instance. Useful if you are running multiple self-hosted GitHub integrations. Defaults to github-ocean. diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx index 76424679bf..8064318f3c 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx @@ -131,10 +131,16 @@ To install the integration using ArgoCD: :::info Placeholder Replacement Required Be sure to replace the `` and `` placeholders with your actual values. If you are using a self-hosted GitHub instance, update the `githubHost` value to point to your instance. -For multi-organization support, use a **classic PAT token** and specify multiple organizations in the array +For multi-organization support, use a **classic PAT token** and specify multiple organizations in the Port mapping -```yaml -githubMultiOrganizations: ["org1", "org2", "org3"] # Array format +```yaml showLineNumbers +deleteDependentEntities: true +createMissingRelatedEntities: true +enableMergeEntity: true +organizations: + - org1 + - org2 +# ... rest of your mapping (repositoryType, resources, etc.) ... ``` ::: diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx index 052cf81e3c..d01ca3df5e 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_parameters_table.jsx @@ -46,11 +46,7 @@ export default function ParametersTable({ showingApp }) { Single GitHub organization name to sync data from (for GitHub App or Fine-grained PAT). Required for single-org authentication. ❌ - - integration.config.githubMultiOrganizations - Array of GitHub organization names to sync data from (for Classic PAT). For multi-org support, use a classic PAT token. Leave empty with classic PAT to sync all accessible organizations. - ❌ - + {/* Multi-organization is configured in Port App Config (organizations) via the mapping, not integration.config */} integration.config.githubHost The API endpoint for your GitHub instance. For GitHub Enterprise Cloud, this will be https://api.<SUBDOMAIN>.ghe.com. Defaults to https://api.github.com if not provided. diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx index f73669b8b7..2828995c0d 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx @@ -31,10 +31,10 @@ This page outlines the following steps: Starting from **version 3.0.0-beta**, the GitHub integration supports syncing data from multiple GitHub organizations. :::info Multi-organization configuration -- Classic PAT: optional `githubMultiOrganizations: ["org1", "org2", "org3"]`. If omitted, all accessible orgs are synced. -- GitHub App and fine-grained PAT: use a single `githubOrganization`. -- Do not set both `githubOrganization` and `githubMultiOrganizations` at the same time. +- GitHub App and fine-grained PAT: use `githubOrganization`. +- Do not set `githubOrganization` if you intend syncing multi organizations, instead optionally list the organizations you want in your Port mapping or leave empty to sync all organizations the Classic Personal Access Token user is a member of. - Performance: syncing multiple organizations increases API calls and may slow down the integration. +- Classic PAT: Multi organization is only support for Classic Personal Access Tokens ::: ### Create access token diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md index de2e044d19..22b61d872e 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md @@ -14,14 +14,13 @@ The new Ocean-powered GitHub integration comes with several key improvements: ### Multi-organization support (v3.0.0-beta) -The GitHub integration now supports ingesting data from multiple GitHub organizations starting from **version 3.0.0-beta**. This is configured using the `githubOrganization` and `githubMultiOrganizations` parameters: +The GitHub integration now supports ingesting data from multiple GitHub organizations starting from **version 3.0.0-beta**. Configure one organization using `githubOrganization`, or list multiple organizations in your Port mapping under `organizations`: ```yaml showLineNumbers -integration: - config: - githubMultiOrganizations: ["org1", "org2", "org3"] # Classic PAT only - # OR - githubOrganization: "my-org" # GitHub App or Fine-grained PAT only +# port-app-config.yml (Port mapping) +organizations: + - org1 + - org2 ``` ### Authentication model @@ -92,9 +91,9 @@ A key change is how we denote custom attributes. We now add a double underscore ### Files & GitOps -:::info Organization field in file selectors -The `organization` field is optional if `githubOrganization` is set globally. It is required when no global organization is provided (e.g., Classic PAT syncing multiple orgs). -::: +::::info Organization field in file selectors +The `organization` field is optional when `githubOrganization` is set in the deployment config. It is required when `githubOrganization` is not provided. +::::
Existing configuration (click to expand) @@ -135,7 +134,7 @@ 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 no global org + 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 repos: - name: MyRepo # ✅ new key:value pairs rather than a string. @@ -288,7 +287,6 @@ resources: labels: "[.labels[].name]" status: ".state" createdAt: ".created_at" - link: ".html_url" relations: repository: ".repo" # ❌ changed ``` @@ -398,9 +396,9 @@ resources: ### Folders -:::info Organization field in folder selectors -The `organization` field is optional if `githubOrganization` is set globally. It is required when no global organization is provided (e.g., Classic PAT syncing multiple orgs). -::: +::::info Organization field in folder selectors +The `organization` field is optional when `githubOrganization` is set in the deployment config. It is required when no deployment-level organization is provided (e.g., Classic PAT with multiple organizations defined in your Port mapping). +:::: For the `folder` kind, the `folder.name` attribute is no longer part of the response. Instead, you can easily derive the folder name from the `folder.path` using a JQ expression, as shown in the example below: @@ -440,7 +438,7 @@ resources: query: "true" folders: - path: apps/* - organization: my-org # Optional if githubOrganization is set; required if no global org + organization: my-org # Optional if githubOrganization is set; required if not set repos: - name: backend-service # ✅ new, now has a 'name' key branch: main # ✅ new, optional branch name @@ -549,9 +547,9 @@ This section provides a high-level summary of the key changes for mappings. | Area | Old Value | New Value | Notes | |---|---|---|---| -| **Multi-Organization** | N/A | `githubOrganization` and `githubMultiOrganizations` configuration | New configuration to support multiple organizations. **Classic PAT supports multiple orgs using `githubMultiOrganizations`; GitHub App and Fine-grained PAT support exactly 1 org using `githubOrganization`**. Syncing multiple organizations increases API calls and may slow down the integration. | -| **File Organization** | N/A | `organization: "my-org"` | Optional if `githubOrganization` is set; required when no global org (e.g., Classic PAT multi-org). | -| **Folder Organization** | N/A | `organization: "my-org"` | Optional if `githubOrganization` is set; required when no global org (e.g., Classic PAT multi-org). | +| **Multi-Organization** | N/A | `githubOrganization` is not optional | **Classic PAT supports multiple orgs using the `organization` parameter in Port mapping; GitHub App and Fine-grained PAT do not support multi organization and there required the `githubOrganization` configuration**. Syncing multiple organizations increases API calls and may slow down the integration. | +| **File Organization** | N/A | `organization: "my-org"` | Optional if `githubOrganization` is set; required when not (e.g., Classic PAT multi-org). | +| **Folder Organization** | N/A | `organization: "my-org"` | Optional if `githubOrganization` is set; required when not set(e.g., Classic PAT multi-org). | | **Authentication** | GitHub App Installation | PAT or Self-Created GitHub App | The integration can be authenticated using a Personal Access Token (PAT) or a self-created GitHub App. **Multi-org requires classic PAT**. | | **Webhooks** | App Webhook | Automatic Setup by Integration | The integration now manages its own webhooks for live events. This requires `webhook` permissions and `liveEvents.baseUrl` to be set. | | **Workflow Runs** | 10 per repository | 100 per workflow | The number of ingested workflow runs has been increased. | From aaf602eaec3179ff1fa624fa47dabc2ea8731764 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Mon, 20 Oct 2025 10:56:56 +0100 Subject: [PATCH 06/10] fix: update migration guide --- .../sync-data-to-catalog/git/github-ocean/migration-guide.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md index 22b61d872e..76ed576902 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md @@ -17,10 +17,13 @@ The new Ocean-powered GitHub integration comes with several key improvements: The GitHub integration now supports ingesting data from multiple GitHub organizations starting from **version 3.0.0-beta**. Configure one organization using `githubOrganization`, or list multiple organizations in your Port mapping under `organizations`: ```yaml showLineNumbers -# port-app-config.yml (Port mapping) +deleteDependentEntities: true +createMissingRelatedEntities: true +enableMergeEntity: true organizations: - org1 - org2 +# ... rest of your mapping (repositoryType, resources, etc.) ... ``` ### Authentication model From 6cee11bf6c7941cb9bf3057281de01e2326ca80f Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Mon, 20 Oct 2025 13:51:55 +0100 Subject: [PATCH 07/10] fix: update docs --- .../sync-data-to-catalog/git/github-ocean/github-ocean.md | 2 ++ .../git/github-ocean/installation/installation.mdx | 6 +++--- .../git/github-ocean/migration-guide.md | 2 ++ 3 files changed, 7 insertions(+), 3 deletions(-) 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 82632af97f..6ef1ba1cd9 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 @@ -45,6 +45,8 @@ organizations: - **With GitHub App**: Specify exactly one organization: `githubOrganization: "my-org"` - **With Fine-grained PAT**: Specify exactly one organization: `githubOrganization: "my-org"` +**Precedence:** If `githubOrganization` is set in the deployment config and `organizations` are also listed in Port mapping, the integration prioritizes single‑organization behavior and syncs only the `githubOrganization`. + **Performance consideration:** Syncing multiple organizations will increase the number of API calls to GitHub and may slow down the integration. The more organizations you sync, the longer the resync time and the higher the API rate limit consumption. Consider syncing only the organizations you need. ::: diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx index 2828995c0d..7947fdfaef 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx @@ -31,10 +31,10 @@ This page outlines the following steps: Starting from **version 3.0.0-beta**, the GitHub integration supports syncing data from multiple GitHub organizations. :::info Multi-organization configuration -- GitHub App and fine-grained PAT: use `githubOrganization`. -- Do not set `githubOrganization` if you intend syncing multi organizations, instead optionally list the organizations you want in your Port mapping or leave empty to sync all organizations the Classic Personal Access Token user is a member of. +- GitHub App and fine-grained PAT: use `githubOrganization` (single organization). +- Classic PAT: to sync multiple organizations, list them in your Port mapping under `organizations`. +- Precedence: if `githubOrganization` is set in the deployment config and `organizations` are listed in Port mapping, the integration syncs only the `githubOrganization` (single‑org behavior). - Performance: syncing multiple organizations increases API calls and may slow down the integration. -- Classic PAT: Multi organization is only support for Classic Personal Access Tokens ::: ### Create access token diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md index 76ed576902..28f42e52d4 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md @@ -26,6 +26,8 @@ organizations: # ... rest of your mapping (repositoryType, resources, etc.) ... ``` +**Precedence:** If `githubOrganization` is set in the deployment config and `organizations` are listed in Port mapping, the integration syncs only the `githubOrganization` (single‑org behavior). + ### Authentication model #### Personal access token (PAT) From 63ed56dc500035becd41cd473b9b253479b1b4db Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Tue, 21 Oct 2025 08:44:57 +0100 Subject: [PATCH 08/10] fix: handle collapsibles --- .../git/github-ocean/github-ocean.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) 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 6ef1ba1cd9..60db22a546 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 @@ -87,7 +87,7 @@ When configuring the integration **using Port**, the YAML configuration is globa The `repositoryType` parameter filters which repositories are ingested. It corresponds to the `type` parameter in GitHub's [List organization repositories](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-organization-repositories) API.
-Possible values: +Possible values (Click to expand) * `all` (default): All repositories accessible to the provided token. * `public`: Public repositories. @@ -218,6 +218,8 @@ The following configuration fetches all `package.json` files from "MyRepo" and " The `organization` field is optional when `githubOrganization` is set in the deployment config. It is required when no deployment-level organization is provided (e.g., Classic PAT with multiple organizations defined in your Port mapping). ::: +
+Package file mapping example (click to expand) ```yaml showLineNumbers resources: - kind: file @@ -244,6 +246,8 @@ resources: project_version: .content.version license: .content.license ``` +
+ :::tip Test your mapping After adding the `file` kind to your mapping configuration, click on the `Resync` button. When you open the mapping configuration again, you will see real examples of files fetched from your GitHub organization. @@ -743,6 +747,8 @@ For example, say you want to track/manage a project's dependencies in Port. One The following configuration fetches a `package.json` file from a specific repository, and creates an entity for each of the dependencies in the file, based on the `package` blueprint: +
+File mapping example for mulitiple entities (click to expand) ```yaml showLineNumbers resources: - kind: file @@ -770,6 +776,7 @@ resources: version: .item.value relations: {} ``` +
#### Multi-document YAML files @@ -798,6 +805,8 @@ When `skipParsing` is set to `true`, the file content will be kept in its origin Here's an example that ingests the raw content of a `values.yaml` file into the `content` property of a `file` entity: +
+File mapping example for ingesting raw content (click to expand) ```yaml resources: - kind: file @@ -819,6 +828,7 @@ resources: properties: content: .content ``` +
#### Limitations From da38077386076f3b76a2ad69b91641005494aff9 Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Tue, 21 Oct 2025 09:34:20 +0100 Subject: [PATCH 09/10] fix: handle pr reviews --- .../git/github-ocean/github-ocean.md | 11 +++++------ .../github-ocean/installation/_install_methods.mdx | 2 +- .../git/github-ocean/installation/installation.mdx | 4 ++-- .../git/github-ocean/migration-guide.md | 13 ++++++------- 4 files changed, 14 insertions(+), 16 deletions(-) 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 60db22a546..26ade61fc9 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 @@ -22,7 +22,7 @@ Here's what you can do with the GitHub integration: ### Multi-organization support -The GitHub integration supports syncing data from multiple GitHub organizations starting from **version 3.0.0-beta**. You can configure which organizations to sync using a single-org `githubOrganization`, or by listing organizations in your Port mapping (`organizations`). +The GitHub integration supports syncing data from multiple GitHub organizations starting from **version 3.0.0-beta**. You can configure which organizations to sync using a single-org `githubOrganization`, or by listing organizations in your port mapping (`organizations`).
Mapping multi organizations (Click to expand) @@ -41,11 +41,10 @@ organizations: :::caution Authentication and configuration requirements: - **With classic PAT**: - - Specify organizations in PortMapping: `organizations: ["org1", "org2", "org3"]` -- **With GitHub App**: Specify exactly one organization: `githubOrganization: "my-org"` -- **With Fine-grained PAT**: Specify exactly one organization: `githubOrganization: "my-org"` + - Specify organizations in port mapping: `organizations: ["org1", "org2", "org3"]` +- **With GitHub App or Fine-grained PAT**: Specify exactly one organization by setting the `githubOrganization` in the environment variables: `githubOrganization: "my-org"` -**Precedence:** If `githubOrganization` is set in the deployment config and `organizations` are also listed in Port mapping, the integration prioritizes single‑organization behavior and syncs only the `githubOrganization`. +**Precedence:** If `githubOrganization` is set in the environment variables or config and `organizations` are also listed in port mapping, the integration prioritizes single‑organization behavior and syncs only the `githubOrganization`. **Performance consideration:** Syncing multiple organizations will increase the number of API calls to GitHub and may slow down the integration. The more organizations you sync, the longer the resync time and the higher the API rate limit consumption. Consider syncing only the organizations you need. ::: @@ -215,7 +214,7 @@ 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 deployment config. It is required when no deployment-level organization is provided (e.g., Classic PAT with multiple organizations defined in your Port mapping). +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). :::
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx index 8064318f3c..09f42b2a65 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx @@ -131,7 +131,7 @@ To install the integration using ArgoCD: :::info Placeholder Replacement Required Be sure to replace the `` and `` placeholders with your actual values. If you are using a self-hosted GitHub instance, update the `githubHost` value to point to your instance. -For multi-organization support, use a **classic PAT token** and specify multiple organizations in the Port mapping +For multi-organization support, use a **classic PAT token** and specify multiple organizations in the port mapping ```yaml showLineNumbers deleteDependentEntities: true diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx index 7947fdfaef..8e5e8fac32 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx @@ -32,8 +32,8 @@ Starting from **version 3.0.0-beta**, the GitHub integration supports syncing da :::info Multi-organization configuration - GitHub App and fine-grained PAT: use `githubOrganization` (single organization). -- Classic PAT: to sync multiple organizations, list them in your Port mapping under `organizations`. -- Precedence: if `githubOrganization` is set in the deployment config and `organizations` are listed in Port mapping, the integration syncs only the `githubOrganization` (single‑org behavior). +- Classic PAT: to sync multiple organizations, list them in your port mapping under `organizations`. +- Precedence: if `githubOrganization` is set in the environment variables or config and `organizations` are listed in port mapping, the integration syncs only the `githubOrganization` (single‑org behavior). - Performance: syncing multiple organizations increases API calls and may slow down the integration. ::: diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md index 28f42e52d4..48694034c9 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/migration-guide.md @@ -10,11 +10,10 @@ The new Ocean-powered GitHub integration comes with several key improvements: - **Enhanced performance** - Faster resyncs thanks to improved API efficiency, making your data available sooner. - **Better selectors** - More granular control over what you sync with improved selectors for `pull requests`, `issues`, `dependabot alerts`, `codescanning alerts`, `files`, and `folders`. -## Major changes -### Multi-organization support (v3.0.0-beta) +### Multi-organization support -The GitHub integration now supports ingesting data from multiple GitHub organizations starting from **version 3.0.0-beta**. Configure one organization using `githubOrganization`, or list multiple organizations in your Port mapping under `organizations`: +The GitHub integration supports ingesting data from multiple GitHub organizations starting from **version 3.0.0-beta**. Configure one organization using `githubOrganization`, in your environment variables or list multiple organizations in your port mapping under `organizations`: ```yaml showLineNumbers deleteDependentEntities: true @@ -26,7 +25,7 @@ organizations: # ... rest of your mapping (repositoryType, resources, etc.) ... ``` -**Precedence:** If `githubOrganization` is set in the deployment config and `organizations` are listed in Port mapping, the integration syncs only the `githubOrganization` (single‑org behavior). +**Precedence:** If `githubOrganization` is set in the environment variables or config and `organizations` are listed in port mapping, the integration syncs only the `githubOrganization` (single‑org behavior). ### Authentication model @@ -97,7 +96,7 @@ A key change is how we denote custom attributes. We now add a double underscore ### Files & GitOps ::::info Organization field in file selectors -The `organization` field is optional when `githubOrganization` is set in the deployment config. It is required when `githubOrganization` is not provided. +The `organization` field is optional when `githubOrganization` is set in the environment variables and it is required when not provided there. ::::
@@ -402,7 +401,7 @@ resources: ### Folders ::::info Organization field in folder selectors -The `organization` field is optional when `githubOrganization` is set in the deployment config. It is required when no deployment-level organization is provided (e.g., Classic PAT with multiple organizations defined in your Port mapping). +The `organization` field is optional when `githubOrganization` is set in the environment variables and is required when not provided (e.g., Classic PAT with multiple organizations defined in your port mapping). :::: For the `folder` kind, the `folder.name` attribute is no longer part of the response. Instead, you can easily derive the folder name from the `folder.path` using a JQ expression, as shown in the example below: @@ -552,7 +551,7 @@ This section provides a high-level summary of the key changes for mappings. | Area | Old Value | New Value | Notes | |---|---|---|---| -| **Multi-Organization** | N/A | `githubOrganization` is not optional | **Classic PAT supports multiple orgs using the `organization` parameter in Port mapping; GitHub App and Fine-grained PAT do not support multi organization and there required the `githubOrganization` configuration**. Syncing multiple organizations increases API calls and may slow down the integration. | +| **Multi-Organization** | N/A | `githubOrganization` is not optional | **Classic PAT supports multiple orgs using the `organization` parameter in port mapping; GitHub App and Fine-grained PAT do not support multi organization and there required the `githubOrganization` configuration**. Syncing multiple organizations increases API calls and may slow down the integration. | | **File Organization** | N/A | `organization: "my-org"` | Optional if `githubOrganization` is set; required when not (e.g., Classic PAT multi-org). | | **Folder Organization** | N/A | `organization: "my-org"` | Optional if `githubOrganization` is set; required when not set(e.g., Classic PAT multi-org). | | **Authentication** | GitHub App Installation | PAT or Self-Created GitHub App | The integration can be authenticated using a Personal Access Token (PAT) or a self-created GitHub App. **Multi-org requires classic PAT**. | From c4e02b4f569c4bd53f6ac54dcc50116a059fb2db Mon Sep 17 00:00:00 2001 From: emekanwaoma Date: Tue, 21 Oct 2025 10:57:15 +0100 Subject: [PATCH 10/10] fix: add show line numbers to yaml examples --- .../sync-data-to-catalog/git/github-ocean/github-ocean.md | 2 +- .../sync-data-to-catalog/git/github-ocean/gitops/gitops.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) 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 26ade61fc9..096663d1c8 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 @@ -806,7 +806,7 @@ Here's an example that ingests the raw content of a `values.yaml` file into the
File mapping example for ingesting raw content (click to expand) -```yaml +```yaml showLineNumbers resources: - kind: file selector: 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 e980e5dc61..22d2aba330 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 @@ -129,7 +129,7 @@ For example, say you want to ingest a `package.json` file form your repository. Optional if `githubOrganization` is set; required only when not set. ::: -```yaml +```yaml showLineNumbers resources: ... - kind: file @@ -152,7 +152,7 @@ resources: The `selector.files.path` key also supports glob patterns, so you can ingest multiple files by matching against a pattern and create an entity in Port for each one, for example: -```yaml +```yaml showLineNumbers - kind: file selector: query: 'true'