Skip to content

Add Documentation Note for Deleting Unwanted Entities After First Time Installs of GitHub Ocean Multi Orgs #2932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+82 −51
Open

Add Documentation Note for Deleting Unwanted Entities After First Time Installs of GitHub Ocean Multi Orgs #2932

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a6b14f7
fix: update documentation for entity deletion threshold
emekanwaoma Oct 21, 2025
77430ec
Merge branch 'main' into PORT-16636
mk-armah Oct 22, 2025
0d299c6
Merge branch 'main' into PORT-16636
mk-armah Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 50 additions & 50 deletions ...log/git/github-ocean/examples/examples.md → ...a-to-catalog/git/github-ocean/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,56 +2,56 @@
sidebar_position: 2
---

import RepositoryBlueprint from './\_github_exporter_example_repository_blueprint.mdx'
import PRBlueprint from './\_github_exporter_example_pull_request_blueprint.mdx'
import PortAppConfig from './\_github_exporter_example_port_app_config.mdx'
import GitHubResources from '../\_github_exporter_supported_resources.mdx'

import UsersBlueprint from './example-repository-admins/\_github_exporter_example_users_blueprint.mdx'
import GithubUsersBlueprint from './example-repository-admins/\_github_exporter_example_github_users_blueprint.mdx'
import RepositoryAdminBlueprint from './example-repository-admins/\_github_export_example_repository_with_admins_relation_blueprint.mdx'
import RepositoryAdminAppConfig from './example-repository-admins/\_github_exporter_example_admins_users_port_app_config.mdx'

import IssueBlueprint from './example-issue/\_git_exporter_example_issue_blueprint.mdx'
import PortIssueAppConfig from './example-issue/\_github_exporter_example_issue_port_app_config.mdx'
import RepoEnvironmentBlueprint from './example-deployments-environments/\_github_exporter_example_environment_blueprint.mdx'
import DeploymentBlueprint from './example-deployments-environments/\_github_exporter_example_deployment_blueprint.mdx'
import PortRepoDeploymentAndEnvironmentAppConfig from './example-deployments-environments/\_github_exporter_example_deployments_and_environments_port_app_config.mdx'

import TagBlueprint from './example-repository-release-tag/\_github_exporter_example_tag_blueprint.mdx'
import ReleaseBlueprint from './example-repository-release-tag/\_github_exporter_example_release_blueprint.mdx'
import RepositoryTagReleaseAppConfig from './example-repository-release-tag/\_github_exporter_example_release_tag_port_app_config.mdx'

import PackageBlueprint from './example-file-kind/\_example_package_blueprint.mdx'
import PackageAppConfig from './example-file-kind/\_package_json_app_config.mdx'
import FileBlueprint from './example-file-kind/\_example_file_blueprint.mdx'
import RepoFileAppConfig from './example-file-kind/\_file_repo_app_config.mdx'

import TeamWithMembersBlueprint from './example-team-members/\_github_exporter_team_blueprint.mdx'
import TeamMemberBlueprint from './example-team-members/\_github_exporter_team_member_blueprint.mdx'
import TeamMemberConfig from './example-team-members/\_github_team_member_port_app_config.mdx'

import TeamBlueprint from './example-repository-teams/\_github_export_example_team_blueprint.mdx'
import RepositoryTeamBlueprint from './example-repository-teams/\_github_export_example_repository_with_teams_relation_blueprint.mdx'
import PortRepositoryTeamMappingAppConfig from './example-repository-teams/\_github_exporter_example_repository_with_teams_port_app_config.mdx'

import CollaboratorBlueprint from './example-repository-collaborators/\_github_exporter_example_collaborator_blueprint.mdx'
import PortRepositoryCollaboratorAppConfig from './example-repository-collaborators/\_github_exporter_example_repository_collaborator_port_app_config.mdx'

import PortMonoRepoAppConfig from './example-monorepo/\_github_exporter_example_monorepo_port_app_config.mdx'
import WorkflowBlueprint from './example-workflow-workflowrun/\_git_exporter_example_workflow_blueprint.mdx'
import WorkflowRunBlueprint from './example-workflow-workflowrun/\_git_exporter_example_workflow_run_blueprint.mdx'
import PortWfWfrAppConfig from './example-workflow-workflowrun/\_github_exporter_example_wf_wfr_port_app_config.mdx'

import BranchBlueprint from './example-branch/\_git_exporter_example_branch_blueprint.mdx'
import PortBrAppConfig from './example-branch/\_github_exporter_example_branch_port_app_config.mdx'

import DependabotAlertBlueprint from './example-repository-alerts/\_github_exporter_example_dependabot_alert_blueprint.mdx'
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'
import RepositoryBlueprint from './examples/\_github_exporter_example_repository_blueprint.mdx'
import PRBlueprint from './examples/\_github_exporter_example_pull_request_blueprint.mdx'
import PortAppConfig from './examples/\_github_exporter_example_port_app_config.mdx'
import GitHubResources from './\_github_exporter_supported_resources.mdx'

import UsersBlueprint from './examples/example-repository-admins/\_github_exporter_example_users_blueprint.mdx'
import GithubUsersBlueprint from './examples/example-repository-admins/\_github_exporter_example_github_users_blueprint.mdx'
import RepositoryAdminBlueprint from './examples/example-repository-admins/\_github_export_example_repository_with_admins_relation_blueprint.mdx'
import RepositoryAdminAppConfig from './examples/example-repository-admins/\_github_exporter_example_admins_users_port_app_config.mdx'

import IssueBlueprint from './examples/example-issue/\_git_exporter_example_issue_blueprint.mdx'
import PortIssueAppConfig from './examples/example-issue/\_github_exporter_example_issue_port_app_config.mdx'
import RepoEnvironmentBlueprint from './examples/example-deployments-environments/\_github_exporter_example_environment_blueprint.mdx'
import DeploymentBlueprint from './examples/example-deployments-environments/\_github_exporter_example_deployment_blueprint.mdx'
import PortRepoDeploymentAndEnvironmentAppConfig from './examples/example-deployments-environments/\_github_exporter_example_deployments_and_environments_port_app_config.mdx'

import TagBlueprint from './examples/example-repository-release-tag/\_github_exporter_example_tag_blueprint.mdx'
import ReleaseBlueprint from './examples/example-repository-release-tag/\_github_exporter_example_release_blueprint.mdx'
import RepositoryTagReleaseAppConfig from './examples/example-repository-release-tag/\_github_exporter_example_release_tag_port_app_config.mdx'

import PackageBlueprint from './examples/example-file-kind/\_example_package_blueprint.mdx'
import PackageAppConfig from './examples/example-file-kind/\_package_json_app_config.mdx'
import FileBlueprint from './examples/example-file-kind/\_example_file_blueprint.mdx'
import RepoFileAppConfig from './examples/example-file-kind/\_file_repo_app_config.mdx'

import TeamWithMembersBlueprint from './examples/example-team-members/\_github_exporter_team_blueprint.mdx'
import TeamMemberBlueprint from './examples/example-team-members/\_github_exporter_team_member_blueprint.mdx'
import TeamMemberConfig from './examples/example-team-members/\_github_team_member_port_app_config.mdx'

import TeamBlueprint from './examples/example-repository-teams/\_github_export_example_team_blueprint.mdx'
import RepositoryTeamBlueprint from './examples/example-repository-teams/\_github_export_example_repository_with_teams_relation_blueprint.mdx'
import PortRepositoryTeamMappingAppConfig from './examples/example-repository-teams/\_github_exporter_example_repository_with_teams_port_app_config.mdx'

import CollaboratorBlueprint from './examples/example-repository-collaborators/\_github_exporter_example_collaborator_blueprint.mdx'
import PortRepositoryCollaboratorAppConfig from './examples/example-repository-collaborators/\_github_exporter_example_repository_collaborator_port_app_config.mdx'

import PortMonoRepoAppConfig from './examples/example-monorepo/\_github_exporter_example_monorepo_port_app_config.mdx'
import WorkflowBlueprint from './examples/example-workflow-workflowrun/\_git_exporter_example_workflow_blueprint.mdx'
import WorkflowRunBlueprint from './examples/example-workflow-workflowrun/\_git_exporter_example_workflow_run_blueprint.mdx'
import PortWfWfrAppConfig from './examples/example-workflow-workflowrun/\_github_exporter_example_wf_wfr_port_app_config.mdx'

import BranchBlueprint from './examples/example-branch/\_git_exporter_example_branch_blueprint.mdx'
import PortBrAppConfig from './examples/example-branch/\_github_exporter_example_branch_port_app_config.mdx'

import DependabotAlertBlueprint from './examples/example-repository-alerts/\_github_exporter_example_dependabot_alert_blueprint.mdx'
import CodeScanAlertBlueprint from './examples/example-repository-alerts/\_github_exporter_example_codeScan_alert_blueprint.mdx'
import PortRepositoryDependabotAlertMappingAppConfig from './examples/example-repository-alerts/\_github_exporter_example_repo_dependabot_port_app_config.mdx'

import OrganizationBlueprint from './examples/example-organization/\_github_exporter_example_organization_blueprint.mdx'
import OrganizationAppConfig from './examples/example-organization/\_github_exporter_example_organization_port_app_config.mdx'


# Resource mapping examples
Expand Down
3 changes: 3 additions & 0 deletions ...ild-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,14 @@ organizations:
:::caution Authentication and configuration requirements:
- **With classic PAT**:
- Specify organizations in port mapping: `organizations: ["org1", "org2", "org3"]`
- If `organizations` are not specified, the integration will sync all organizations the classic PAT is scoped to.
- **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.

**Default mapping behavior:** First‑time installs may sync more than intended, since organizations aren’t scoped yet. Refer to [installation guide](./installation) on how to ensure a clean catalogue after you scope out required organization.
:::


Expand Down
30 changes: 29 additions & 1 deletion ...are-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,39 @@ 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`.
- Classic PAT:
- To sync multiple organizations, list them in your port mapping under `organizations`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

indicate the location of the organization parameter, on top level ?

- If `organizations` are not specified, the integration will sync all organizations the classic PAT is scoped to.
- 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.
:::

#### Cleanup after restricting organizations

If you initially synced multiple organizations (e.g., on a first‑time install before your mapping was ready) and later restrict organizations in your mapping, set `entityDeletionThreshold: 1` temporarily and resync to ensure previously ingested, now‑unwanted entities are deleted. Revert the threshold afterwards (default ≈ 0.9) or remove completely.

<details>
<summary><b>Entity deletion threshold (click to expand)</b></summary>

```yaml showLineNumbers

entityDeletionThreshold: 1
resources:
- kind: organization
selector:
query: 'true'
port:
entity:
mappings:
identifier: .login
title: .login
blueprint: '''githubOrganization'''
properties:
login: .login
id: .id
```
</details>
Comment on lines +42 to +66
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove


### Create access token

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.
Expand Down