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 outlines the following steps:

  1. How to create an access token to give the integration permissions to query your Github organization.
  2. How to deploy the integration in the configuration that fits your use case.

Prerequisites​

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

Setup​

Create access token​

To allow Port to fetch data from your GitHub Organization, you need to create an access token. Port supports two types of tokens for authentication: personal access tokens and GitHub app installation tokens.

A Personal Access Token (PAT) is suitable if you're the only one managing the integration and don't need frequent credential rotation.
To create a personal access token see Github's managing your personal access tokens.

  • The token must belong to a user with access to the relevant Github resources (e.g., repositories, teams).
Required permissions

These are the necessary permissions if you're creating a fine-grained PAT.

Repository permissions:

  • Actions: Readonly
  • Content: Readonly
  • Metadata: Readonly
  • Pull Requests: Readonly
  • Code scanning alerts: Readonly
  • Dependabot alerts: Readonly
  • Deployments: Readonly
  • Environments: Readonly

Organization permissions:

  • Webhooks: Read and Write (for managing webhook)
Default permissions

You will be prompted to confirm the above listed permissions when creating a personal access token.

Permissions can be given to selected repositories in your organization, or to all repositories.
You can reconfigure the permission at any time, giving it access to new repositories, or removing access.

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.
Event grouping behavior

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.

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.

Deploy the integration​

To deploy the integration, you will need your Port CLIENT_ID and CLIENT_SECRET.

To get your Port credentials, go to your Port application, click on the ... button in the top right corner, and select Credentials. Here you can view and copy your CLIENT_ID and CLIENT_SECRET:

Choose the installation method that best suits your needs:

Our integration can be directly run as a docker container, it can be deployed on any platform that allows deploying images as containers such as: K8S, ECS, AWS App Runner, etc.

You can pull the Docker image by running:

docker pull ghcr.io/port-labs/port-ocean-github-ocean:1.2.0-beta

Run the following command to start the app:

docker run \
-e OCEAN__PORT__CLIENT_ID="<PORT_CLIENT_ID>" \
-e OCEAN__PORT__CLIENT_SECRET="<PORT_CLIENT_SECRET>" \
-e OCEAN__PORT__BASE_URL="https://api.getport.io" \
-e OCEAN__BASE_URL="<https.example.com>" \ #optional, only required if you want to enable live-events
-e OCEAN__EVENT_LISTENER__TYPE="POLLING" \
-e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST="<GITHUB_HOST>" \ # e.g https://api.github.com
-e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION="<GITHUB_ORGANIZATION>" \
-e OCEAN__INTEGRATION__IDENTIFIER="github-ocean" \
-e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN="<GITHUB_TOKEN>" \ 
-p 8000:8000 \
ghcr.io/port-labs/port-ocean-github-ocean:1.2.0-beta
Docker parameters

The command above contains placeholder values in angle brackets (e.g., <PORT_CLIENT_ID>). Be sure to replace them with your actual values before running the command.

Env variableDescriptionRequired
OCEAN__PORT__CLIENT_IDPort client id for interacting with the API✅
OCEAN__PORT__CLIENT_SECRETPort client secret for interacting with the API✅
OCEAN__PORT__BASE_URLPort's API Base URL✅
OCEAN__BASE_URLThe base url of the instance where the GitHub integration is hosted, used for real-time updates (e.g. https://mygithuboceanintegration.com).❌
OCEAN__INTEGRATION__CONFIG__WEBHOOK_SECRETA secret to secure webhooks from GitHub. This is optional but highly recommended for security if you enable live-events.❌
OCEAN__EVENT_LISTENER__TYPEDefine the appropriate event listener type to handle incoming events and resync requests from Port. This listener will forward the events to the GitHub Ocean integration. For more details, see the Port Event Listener documentation✅
OCEAN__INTEGRATION__CONFIG__GITHUB_HOSTThe API endpoint for your GitHub instance. For GitHub Enterprise, this will be https://api.<SUBDOMAIN>.ghe.com. Defaults to https://api.github.com if not provided.❌
OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATIONThe GitHub organization the integration was installed in.✅
OCEAN__INTEGRATION__IDENTIFIERA unique identifier for the integration instance. Useful if you are running multiple self-hosted GitHub integrations. Defaults to github-ocean.✅
OCEAN__INTEGRATION__CONFIG__GITHUB_TOKENGithub PAT.✅
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.