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..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 @@ -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 (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__GTIHUB_ORGANIZATION` | The name of your Github organization | | ✅ | +| `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__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..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,8 +25,10 @@ resources: query: 'true' files: - path: 'README.md' + organization: my-org # Optional if githubOrganization is set; required if not set 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..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,6 +8,7 @@ query: 'true' files: - path: '**/package.json' + 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 d86acc7e8f..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,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 # 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/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..7e73dc4187 --- /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,83 @@ +
+Organization blueprint (click to expand) + +```json showLineNumbers +{ + "identifier": "githubOrganization", + "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": { + "type": "string", + "title": "API URL", + "description": "GitHub API URL for the organization" + }, + "reposUrl": { + "type": "string", + "title": "Repositories URL", + "description": "URL to organization's repositories" + }, + "eventsUrl": { + "type": "string", + "title": "Events URL", + "description": "URL to organization's events" + }, + "hooksUrl": { + "type": "string", + "title": "Webhooks URL", + "description": "URL to organization's webhooks" + }, + "issuesUrl": { + "type": "string", + "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/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..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 @@ -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 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. +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..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 @@ -18,6 +18,37 @@ 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 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 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 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. +::: + ### Supported resources @@ -55,7 +86,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. @@ -78,6 +109,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' @@ -94,6 +147,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' @@ -136,10 +191,19 @@ 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 automatically syncs organization-level data (available from **v3.0.0-beta**). + + +:::tip Organization as parent entity +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 Port allows you to fetch `JSON` and `YAML` files from your repositories, and create entities from them in your software catalog. @@ -149,6 +213,12 @@ For example, say you want to manage your `package.json` files in Port. One optio The following configuration fetches all `package.json` files from "MyRepo" and "MyOtherRepo", and creates an entity for each of them, based on the `manifest` blueprint: +:::info Organization field in file selectors +The `organization` field is optional when `githubOrganization` is set in the environment variables and required when it is not provided (e.g., Classic PAT with multiple organizations defined in your port mapping). +::: + +
+Package file mapping example (click to expand) ```yaml showLineNumbers resources: - kind: file @@ -157,6 +227,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 not set # The `repos` key can be used to filter the repositories and branch where files should be fetched repos: - name: MyRepo @@ -174,6 +245,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. @@ -650,6 +723,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", @@ -672,6 +746,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 @@ -679,6 +755,7 @@ resources: query: 'true' files: - path: '**/package.json' + organization: my-org # Optional if githubOrganization is set; required if not set # Note that in this case we are fetching from a specific repository repos: - name: MyRepo @@ -698,9 +775,7 @@ resources: version: .item.value 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 @@ -729,14 +804,20 @@ 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: -```yaml +
+File mapping example for ingesting raw content (click to expand) +```yaml showLineNumbers resources: - kind: file selector: query: 'true' files: - path: values.yaml + organization: my-org # Optional if githubOrganization is set; required if not set skipParsing: true + repos: + - name: MyRepo + branch: main port: entity: mappings: @@ -746,6 +827,7 @@ resources: properties: content: .content ``` +
#### Limitations 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..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 @@ -125,7 +125,11 @@ 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: -```yaml +:::info Organization field for file selectors +Optional if `githubOrganization` is set; required only when not set. +::: + +```yaml showLineNumbers resources: ... - kind: file @@ -133,23 +137,31 @@ resources: query: 'true' files: - path: package.json + organization: my-org # Optional if githubOrganization is set; required if not set + 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: -```yaml +```yaml showLineNumbers - kind: file selector: query: 'true' files: - path: 'resources/*.yml' + organization: my-org # Optional if githubOrganization is set; required if not set + repos: + - name: my-repo + branch: main ``` ### Advantages 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..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 @@ -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_ORGANIZATION + Single GitHub organization name to sync data from a single organization. Required for single-org authentication. + ❌ 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..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 @@ -128,8 +128,20 @@ 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 port mapping + +```yaml showLineNumbers +deleteDependentEntities: true +createMissingRelatedEntities: true +enableMergeEntity: true +organizations: + - org1 + - org2 +# ... rest of your mapping (repositoryType, resources, etc.) ... +``` ::: ```yaml showLineNumbers 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..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 @@ -43,9 +43,10 @@ export default function ParametersTable({ showingApp }) { integration.config.githubOrganization - The GitHub organization to sync data from. - ✅ + Single GitHub organization name to sync data from (for GitHub App or Fine-grained PAT). Required for single-org authentication. + ❌ + {/* 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 ba2ee8e661..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 @@ -26,9 +26,20 @@ This page outlines the following steps: ## Setup +### Multi-organization support + +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` (single organization). +- 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. +::: + ### 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 +47,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 +87,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 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 ef6fc815c3..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,7 +10,22 @@ 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 + +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 +createMissingRelatedEntities: true +enableMergeEntity: true +organizations: + - org1 + - org2 +# ... rest of your mapping (repositoryType, resources, etc.) ... +``` + +**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 @@ -18,6 +33,10 @@ The new Ocean-powered GitHub integration comes with several key improvements: 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 +48,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 using `githubOrganization`. +::: + Below is a sample Helm value for this configuration: ```yaml showLineNumbers integration: config: githubAppId: "" # app client id also works + githubOrganization: "my-org" # Required for single organization support regardlass of token type secrets: githubAppPrivateKey: "" ``` @@ -70,6 +94,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 + +::::info Organization field in file selectors +The `organization` field is optional when `githubOrganization` is set in the environment variables and it is required when not provided there. +:::: +
Existing configuration (click to expand) @@ -109,6 +138,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 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. @@ -128,9 +158,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. 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. ### Repository relationships @@ -260,7 +291,6 @@ resources: labels: "[.labels[].name]" status: ".state" createdAt: ".created_at" - link: ".html_url" relations: repository: ".repo" # ❌ changed ``` @@ -370,6 +400,10 @@ resources: ### Folders +::::info Organization field in folder selectors +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:
@@ -408,6 +442,7 @@ resources: query: "true" folders: - path: apps/* + 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 @@ -512,11 +547,14 @@ 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 | |---|---|---|---| -| **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 | `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. | | **Repository Type** | N/A | `repositoryType` configuration | A new top-level configuration is available to filter repositories by type (`public`, `private`, or `all`). |