> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

GitHub integration troubleshooting

Answers to common bugs and edge cases when using the GitHub Ocean integration.

Why are live events enabled but data is stale?​

Answer (click to expand)

You enabled Live events in the GitHub Ocean integration, but entities are not updating in real time. The last catalog update timestamp shows hours-old data despite active PR and push activity.

Causes and fixes:

  1. Webhook not registered: The integration creates a webhook in GitHub on first sync. If the sync failed or was interrupted, the webhook may not exist. Navigate to your GitHub organization settings, open Webhooks, and verify a Port webhook is present. If not, delete and reinstall the integration.
  2. Rate limit reached: GitHub's webhook delivery can be delayed under rate limiting. Check the integration event log in Port (Data Sources → your integration → Event log) for rate_limit entries. If present, reduce the number of entity kinds being synced or split the integration across multiple GitHub Apps.
  3. Webhook payload size exceeded: Repositories with large collaborator lists can exceed GitHub's webhook payload size limit. Affected events are silently dropped. Workaround: use a periodic sync interval instead of live events for repos with more than ~500 collaborators.
Check the event log first

Data Sources → your GitHub integration → Event log shows every received webhook event. If the list is empty during active repo activity, the webhook is not registered correctly.

Why are entities not deleted after the source is removed in GitHub?​

Answer (click to expand)

A GitHub issue, pull request, or repository was closed or deleted in GitHub, but the entity remains in Port with its old status. A full resync does not remove it.

How Ocean deletion works: Port Ocean only deletes an entity during a resync if the entity is absent from the API response for that kind. If your selector query filters out the closed item (for example it no longer matches .state == "open"), Ocean will not delete the entity but it won't appear in the current sync window.

Fix: To have Port delete entities when they are closed or deleted in GitHub, your selector query must include them in the sync scope so Ocean can compare the full set and identify removals:

- kind: issue
  selector:
    query: "true"

Then set a filter in your blueprint or dashboard to show only open issues, rather than filtering at the selector level.

Closed issues excluded from sync

If you use query: '.state == "open"' in your selector, Ocean will never delete closed issue entities but they simply disappear from the sync window without triggering a deletion.

Why does only a subset of PRs appear in Port?​

Answer (click to expand)

Your mapping targets all PRs since a date (selector.query: .created_at >= "2025-01-01T00:00:00Z") but only a small fraction appear in Port.

Cause: The GitHub API returns a maximum of 100 pull requests per repository per sync by default when only open PRs are requested. PRs beyond that page are not fetched.

Fix: Include closed PRs in the selector state list (alongside open) and verify your mapping includes the state property to distinguish open, closed, and merged:

- kind: pull-request
  selector:
    query: '.created_at >= "2025-01-01T00:00:00Z"'
    states: ["open", "closed"]
Pull request states and the query field

The states list controls which GitHub PR states are returned. The JQ query filters the objects after they are fetched.

Why are workflow runs being deleted on every sync?​

Answer (click to expand)

Workflow run entities disappear from Port on each resync. You want to preserve historical run data but Port keeps removing it.

Cause: The GitHub API only returns the latest 100 workflow runs per repository. On each resync, Ocean compares the current API response to what is in the catalog and deletes anything not in the response - which is all runs beyond the last 100.

Workaround: Add a ttl property to your workflow run blueprint and set it from your mapping. Port will not delete entities whose TTL has not expired, even if they are absent from the sync window:

properties:
  ttl: .created_at

Alternatively, use Port's data archival feature to cold-tier old runs rather than deleting them.

Answer (click to expand)

Ingesting a repository entity fails with a validation error when one of the GitHub teams in the .__teams array does not exist as an entity in Port.

Cause: If you map a relation to an array of identifiers and any one of those identifiers does not exist in the catalog, Port rejects the entire entity upsert.

Fix: use try to skip missing teams:

githubTeams: "[.__teams[] | try (.id | tostring)]"

Fix: subtract known missing IDs:

githubTeams: '([.__teams[].id | tostring] - ["3178082", "8446394"])'
Relations omitted for filtered team IDs

Filtering out missing IDs means those relations will be absent on the entity. The entity is still created - the relation will just be empty for the missing teams.

Can I reuse the same GitHub App when migrating from legacy to Ocean?​

Answer (click to expand)

Yes, you can use the same GitHub App for both the legacy integration and the new Ocean-based data source during migration. They write to the same blueprints using the same entity identifiers, so entities will not be duplicated.

Safe migration steps:

  1. Install the GitHub Ocean integration alongside the existing legacy one.
  2. Verify Ocean is syncing entities correctly (compare entity counts).
  3. Remove entity kinds from the legacy integration one at a time.
  4. Once all kinds are migrated, delete the legacy integration.
Removal order matters

Do not remove a kind from the legacy integration before Ocean has completed at least one full sync of that kind. If you remove a kind from legacy first, Ocean will delete those entities on its next reconcile pass since they are now owned by Ocean but absent from its scope.

Why does the GitHub integration show syncing but nothing is running?​

Answer (click to expand)

The integration status in Data Sources shows a spinning sync indicator but the event log shows no activity and no errors. This persists across browser refreshes.

Cause: This is a known display bug affecting some Ocean integrations where the sync status is not correctly cleared after completion.

Fix: Trigger a manual resync from the Data Sources page. If the integration is self-hosted, restarting the integration pod will also clear the stuck status.