Skip to main content

Check out Port for yourself ➜ 

Installation

Loading version...

The GitHub Ocean integration allows you to model GitHub resources in your software catalog and ingest data into them.

Supported resources OrganizationRepositoryPull RequestIssueFileFolderUserTeamWorkflowWorkflow RunBranchEnvironmentDeploymentReleaseTagDependabot AlertCode Scanning AlertSecret Scanning Alert
Migrating from the old GitHub app?

If you are migrating from the old GitHub app integration, disable the "Create default resources" toggle in the Advanced Configuration section before clicking Connect. If you want to install Github ocean as self-hosted, specify the createPortResourcesOrigin: Empty option in your values file.

Leaving this toggle enabled will create new default blueprints and mappings that may conflict with your existing data. See the migration guide for detailed instructions.

Prerequisites​

  • A GitHub account with permissions to create access tokens.
  • Your Port user role is set to Admin.

Setup​

Choose your preferred authentication and installation method below. Not sure which to pick? See the installation methods overview.

Configuration​

Port integrations use a YAML mapping block to ingest data from the third-party API into Port.
The mapping makes use of the JQ JSON processor to transform data.

Managing your configuration​

You can manage your GitHub Ocean configuration in two ways:

  • Port UI: Go to the data sources page, click on the installed GitHub Ocean integration, and modify the YAML configuration directly. This applies the configuration globally to all organizations and repositories the integration can access.

  • GitHub file: Set repoManagedMapping: true in the integration configuration YAML to load the mapping from a port-app-config.yml file in your GitHub organization. Create this file in the .github-private repository on the default branch for it to take effect as an org-level mapping.

    GitHub file configuration limitations
    • Only org-level configuration is supported — repository-level port-app-config.yml files are not yet supported for GitHub Ocean.
    • Multi-organization setups are not supported when using GitHub file configuration.

Repository type​

The repositoryType parameter filters which repositories are ingested. It corresponds to the type parameter in GitHub's List organization repositories API.

Possible values (click to expand)
  • all (default): All repositories accessible to the provided token.
  • public: Public repositories only.
  • private: Private repositories only.
  • forks: Forked repositories only.
  • sources: Non-forked repositories only.

Multi-organization support​

Starting from version 3.0.0-beta, the GitHub integration supports syncing data from multiple GitHub organizations when authenticating with a classic PAT.

  • Supported authentication: Multi-organization support is available only with a classic PAT. It is not supported when authenticating via a GitHub App.
  • Multi-organization setup: Set organizations: ["org1", "org2", "org3"] in your mapping.
  • All organizations setup: If organizations is not specified, the integration syncs all organizations the classic PAT has access to.
Multi-organization mapping example (click to expand)
deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
organizations:
  - org1
  - org2
# ... rest of your mapping (repositoryType, resources, etc.) ...

Precedence:

If githubOrganization is set in the environment variables or config and organizations are also listed in the Port mapping, the integration prioritizes single-organization behavior and syncs only the githubOrganization.

Performance considerations:

Syncing multiple organizations increases 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.

Default mapping configuration​

This is the complete default mapping for the GitHub Ocean integration.

Complete default mapping (click to expand)
repositoryType: "all"
deleteDependentEntities: true
createMissingRelatedEntities: true
resources:
  - kind: organization
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .login
          title: .login
          blueprint: '"githubOrganization"'
          properties:
            login: .login
            id: .id
            nodeId: .node_id
            url: .url
            reposUrl: .repos_url
            eventsUrl: .events_url
            hooksUrl: .hooks_url
            issuesUrl: .issues_url
            membersUrl: .members_url
            publicMembersUrl: .public_members_url
            avatarUrl: .avatar_url
            description: if .description then .description else "" end
  - kind: repository
    selector:
      query: "true"
      includedFiles:
        - README.md
    port:
      entity:
        mappings:
          identifier: .name
          title: .name
          blueprint: '"githubRepository"'
          properties:
            description: if .description then .description else "" end
            visibility: if .private then "private" else "public" end
            defaultBranch: .default_branch
            readme: .__includedFiles["README.md"]
            url: .html_url
            language: if .language then .language else "" end
          relations:
            organization: .owner.login
  - kind: pull-request
    selector:
      query: "true"
      state: "open"
    port:
      entity:
        mappings:
          identifier: ".head.repo.name + (.id|tostring)"
          title: ".title"
          blueprint: '"githubPullRequest"'
          properties:
            creator: ".user.login"
            assignees: "[.assignees[].login]"
            reviewers: "[.requested_reviewers[].login]"
            status: ".state"
            closedAt: ".closed_at"
            updatedAt: ".updated_at"
            mergedAt: ".merged_at"
            createdAt: ".created_at"
            prNumber: ".id"
            link: ".html_url"
            leadTimeHours: >-
              (.created_at as $createdAt | .merged_at as $mergedAt |
              ($createdAt | sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime) as $createdTimestamp |
              ($mergedAt | if . == null then null else sub("\\..*Z$"; "Z") |
              strptime("%Y-%m-%dT%H:%M:%SZ") | mktime end) as $mergedTimestamp |
              if $mergedTimestamp == null then null else
              (((($mergedTimestamp - $createdTimestamp) / 3600) * 100 | floor) / 100) end)
          relations:
            repository: .__repository

Mapping & examples per resource​

Use the explorer below to view the mapping and blueprint definition for each resource type. For additional resources and advanced configurations, see the examples page.

Capabilities​

The GitHub Ocean integration supports a rich set of data ingestion capabilities. See the capabilities page for full details on each feature.

Key capabilities include:

  • Ingest Git objects — Automatically ingest GitHub resources (repositories, pull requests, issues, and more) based on real-time events.
  • Ingest organizations — Sync organization-level data as parent entities for repositories and teams (available from v3.0.0-beta).
  • Ingest files from repositories — Fetch JSON and YAML files from repositories and create Port entities from their contents.
  • Repository search API — Use GitHub's repository search API for granular repository filtering when ingesting data.
  • Parallel event processing — Configure multiple async workers to handle GitHub webhook events in parallel, preventing race conditions while maintaining event ordering.
  • Personal account ingestion — Optionally ingest the authenticated user's personal GitHub account as a pseudo-organization.

Monitoring and sync status​

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Examples​

For blueprint and configuration examples across all supported resource kinds, see the GitHub Ocean examples page.

To view and test the integration's mapping against live API responses, use the jq playground in your data sources page.

Relevant guides​

For relevant guides and examples, see the guides section.