Merge pull request #2642 from port-labs/OCEAN-27-MULTIPLE-WORKERS-DOC-GITHUB-OCEAN

feat: add event_workers_count config for github ocean

Author: hadar-co

docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.mdx

@@ -40,9 +40,9 @@ To create a personal access token see Github's [managing your personal access to
 
 <details>
   <summary>Required permissions</summary>
-
+  
   These are the necessary permissions if you're creating a fine-grained PAT.
-
+  
   **Repository permissions:**
   - **Content**: Readonly
   - **Metadata**: Readonly
@@ -70,4 +70,37 @@ To set it up, see the [GitHub App installation guide](./github-app.mdx).
 </TabItem>
 </Tabs>
 
+### Configure parallel processing
+
+Configure multiple workers to handle GitHub webhook events in parallel groups, preventing race conditions while maintaining event ordering for related resources.
+
+Starting with Ocean 0.27, a new parameter was added to the configuration, which adjusts the number of async workers spawned for webhook events.
+
+Set `event_workers_count: 4` in your config (default: 1) to enable parallel group processing.
+
+When `event_workers_count > 1`, related GitHub events get grouped together:
+- All PR events (opened, review, status) for PR #123 → same processing group.
+- All issue events for issue #456 → same processing group.
+- Push events grouped by commit SHA.
+
+<details>
+  <summary>Event grouping behavior</summary>
+  
+  **Supported event types:**
+  - **Pull Requests**: Grouped by PR number (`pull_request`, `pull_request_review`, `pull_request_review_comment`)
+  - **Issues**: Grouped by issue number (`issues`, `issue_comment`)
+  - **Pushes**: Grouped by commit SHA (`push`)
+  - **Releases**: Grouped by release ID (`release`)
+  - **Workflow Runs**: Grouped by run ID (`workflow_run`)
+  - **Status Checks**: Grouped by commit SHA (`status`)
+  
+  **Fallback**: If the event type isn't recognized, the payload will be scanned for the first `number`, `id`, or `sha` field.
+
+:::note Processing guarantees
+Events within the same group are processed sequentially to maintain order and prevent conflicts.
+Different groups can be processed in parallel across workers.
+With `event_workers_count: 1`, all events are processed sequentially using a simple queue.
+:::
+</details>
+
 <InstallMethods setupName="classic" />