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:

  • Content: Readonly
  • Metadata: Readonly
  • Pull Requests: 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.

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.