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

[emekanwaoma]

User description

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.

Added docs pages

Please also include the path for the added docs

• Quickstart (/)
• Blueprint (/platform-overview/port-components/blueprint)
• ...

Updated docs pages

Please also include the path for the updated docs

• Quickstart (/)
• Blueprint (/platform-overview/port-components/blueprint)
• ...

---

PR Type

Documentation

---

Description

• Update import paths in examples file to use ./examples/ subdirectory

• Add clarification on classic PAT organization scoping behavior

• Document entity deletion threshold for cleanup after restricting organizations

• Add detailed guidance for first-time installs with multiple organizations

---

Diagram Walkthrough

flowchart LR
  A["GitHub Ocean Docs"] --> B["Import Path Updates"]
  A --> C["Organization Scoping Clarification"]
  A --> D["Entity Deletion Threshold Guide"]
  C --> E["First-time Install Behavior"]
  D --> F["Cleanup Instructions"]

Loading

File Walkthrough

Relevant files

Documentation

examples.md Reorganize import paths to examples subdirectory                  docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples.md Updated all import paths to use ./examples/ subdirectory prefix Reorganized import statements to reflect new directory structure Maintains all existing example blueprints and configurations +50/-50  github-ocean.md Clarify organization scoping and first-time install behavior docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md Added clarification that classic PAT without organizations specified syncs all scoped organizations Added note about first-time installs potentially syncing more than intended Added reference to installation guide for cleanup procedures Emphasized performance considerations for multi-organization syncing +3/-0      installation.mdx Add entity deletion threshold guidance for organization cleanup docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx Added new section "Cleanup after restricting organizations" with detailed instructions Documented entityDeletionThreshold: 1 configuration for entity cleanup Provided YAML example showing how to configure threshold temporarily Clarified classic PAT behavior when organizations are not specified Added collapsible details section with complete configuration example +29/-1

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided - [ ] Create ticket/issue <!-- /create_ticket --create_ticket=true --> </details></td></tr>
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	No custom compliance provided Follow the guide to enable custom compliance check.
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Improve product for safer initial sync The suggestion highlights that the documented manual cleanup process, which requires disabling the entityDeletionThreshold safety feature, is risky and indicates a product gap. It recommends enhancing the integration to provide a safer, automated way to manage initial syncs and cleanups. Examples: docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx [42-66] #### 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 ... (clipped 15 lines) Solution Walkthrough: Before: # docs/.../installation.mdx (User instructions) #### Cleanup after restricting organizations If you synced too many organizations, you must: 1. Restrict organizations in your mapping. 2. Temporarily set `entityDeletionThreshold: 1`. 3. Resync to delete unwanted entities. 4. Revert the `entityDeletionThreshold` back to its default. Example config: ```yaml entityDeletionThreshold: 1 resources: ... #### After: ```markdown # Ideal integration logic (conceptual) class GithubIntegration: def on_config_change(old_config, new_config): removed_orgs = old_config.orgs - new_config.orgs # Automatically and safely clean up entities # from the removed organizations without requiring # manual threshold changes. if is_initial_setup_cleanup(removed_orgs): cleanup_entities_for_orgs(removed_orgs) def resync(): # ... regular sync logic ... # The safety threshold is always active for normal operations. if count_deletions() / total_entities > entityDeletionThreshold: raise Error("Too many entities to delete, aborting.") ... Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies that the PR documents a risky manual workaround for a product limitation, and proposes a more robust, user-friendly product enhancement instead of relying on users to temporarily disable a safety feature.	High
Possible issue	✅ Clarify YAML example to prevent data loss Suggestion Impact: The commit removed the previous standalone "Entity deletion threshold" YAML example that could be misread as a full config, aligning with the suggestion’s intent to prevent misleading replacement of users' configs. code diff: -#### 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> Update the YAML example for entityDeletionThreshold to clarify that it should be added to the user's existing configuration, not replace it, to prevent accidental removal of other resource mappings. docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx [46-66] <details> -<summary><b>Entity deletion threshold (click to expand)</b></summary> +<summary><b>Example: Adding the entity deletion threshold to your configuration (click to expand)</b></summary> ```yaml showLineNumbers +# Add this line at the top of your existing configuration file +entityDeletionThreshold: 1 -entityDeletionThreshold: 1 resources: - - kind: organization + # ... your existing resource mappings remain here ... + - kind: repository selector: - query: 'true' + query: "true" port: entity: mappings: - identifier: .login - title: .login - blueprint: '''githubOrganization''' - properties: - login: .login - id: .id + # ... + - kind: pull-request + selector: + query: "true" + port: + entity: + mappings: + # ... + # ... etc. ``` [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that the documentation example is misleading and could cause users to misconfigure the integration by replacing their entire resource mapping, which would lead to an incomplete sync.	Medium
Update

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2932.d2ngvl90zqbob8.amplifyapp.com