port-labs · sivanel97 · Oct 21, 2025 · Oct 13, 2025 · Oct 14, 2025 · Oct 15, 2025
diff --git a/...are-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx b/...are-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://<org_name.ghe.com>`. 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/.../sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx b/.../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/...-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx b/...-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/...log/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx b/...log/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/...o-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx b/...o-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/...atalog/git/github-ocean/examples/example-file-kind/_package_json_app_config.mdx b/...atalog/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/...examples/example-monorepo/_github_exporter_example_monorepo_port_app_config.mdx b/...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/...amples/example-organization/_github_exporter_example_organization_blueprint.mdx b/...amples/example-organization/_github_exporter_example_organization_blueprint.mdx
@@ -0,0 +1,83 @@
+<details>
+<summary><b>Organization blueprint (click to expand)</b></summary>
+
+```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": {}
+}
+```
+
+</details>
+
diff --git a/.../example-organization/_github_exporter_example_organization_port_app_config.mdx b/.../example-organization/_github_exporter_example_organization_port_app_config.mdx
@@ -0,0 +1,39 @@
+<details>
+
+<summary><b>Port port-app-config.yml (click to expand)</b></summary>
+
+```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
+```
+
+</details>
+
diff --git a/...our-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md b/...our-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`:
+
+<OrganizationBlueprint/>
+
+<RepositoryBlueprint/>
+
+<OrganizationAppConfig/>
+
+:::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