Skip to main content

Check out Port for yourself ➜ 

Installation

This page details how to install Port's GitHub integration (powered by the Ocean framework).

This page helps you choose an authentication method and then deploy the integration using the installation method that fits your setup.

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.

Choose authentication method​

You can create and install a GitHub App directly from Port’s UI using OAuth. This is the recommended approach as it streamlines the entire setup process.

Hosted by Port only

The GitHub App (via Port) setup is available only as a Hosted by Port installation.

Hosted by Port means Port runs and manages the integration for you (no Kubernetes/Docker/CI deployment on your side).

Live event support

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Supported live event triggers (Click to expand)

repository:

  • created
  • edited
  • renamed
  • transferred
  • unarchived
  • publicized
  • privatized
  • archived
  • deleted

pull_request:

  • opened
  • edited
  • ready_for_review
  • reopened
  • synchronize
  • unassigned
  • review_request_removed
  • closed

issues:

  • assigned
  • closed
  • demilestoned
  • edited
  • labeled
  • locked
  • milestoned
  • opened
  • pinned
  • reopened
  • transferred
  • typed
  • unassigned
  • unlabeled
  • unlocked
  • unpinned
  • untyped
  • deleted

release:

  • created
  • edited
  • deleted

create

delete

push

deployment

deployment_status

workflow_run:

  • in_progress
  • requested
  • completed

dependabot_alert:

  • created
  • reopened
  • auto_reopened
  • reintroduced
  • dismissed
  • auto_dismissed
  • fixed

code_scanning_alert:

  • appeared_in_branch
  • reopened
  • created
  • fixed
  • closed_by_user

organization:

  • member_added
  • member_removed

team:

  • created
  • edited
  • deleted
  • added_to_repository

membership:

  • added
  • removed

member:

  • added
  • edited
  • removed

secret_scanning_alert:

  • created
  • publicly_leaked
  • reopened
  • validated
  • resolved
Self-hosted installation

Alternatively, you can install the integration using any of the self-hosted installation methods to update Port in real time using webhooks.

For self-hosted live events, use either Custom GitHub App or Personal access token (PAT).

This installation option means that the integration will be hosted and managed by Port.

  1. Go to the Data sources page of your portal.
  2. Click on the + Data source button in the top-right corner.
  3. Click on Github in the list.
  4. Under Select your installation method, choose Hosted by Port.
  5. Click Connect to start the setup wizard.

Redirect step (important)

During the wizard, you will be redirected to your provider to authorize Port and approve the requested permissions.

On GitHub, you will be prompted to complete an authorization flow to approve the requested permissions and install the app.

  1. Select the organization/account to install the app on.

    Select the GitHub organization or account

  2. Confirm the GitHub app name (or edit it).

    Create GitHub App via Port and continue to GitHub

  3. Authorize the GitHub app on the organization/account.

    Install and authorize the GitHub App (permissions review)

  4. Choose repository access: All repositories or Only select repositories.

    Select repositories to grant access to

  5. Install the app.

    Finalize installation and return to Port

Configuration​

This section describes common configuration options you can use across installation methods.

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.

Default mapping configuration​

This is the default mapping configuration for this integration:

Default mapping configuration (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"
    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: file://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
Last updated on