Skip to main content

Check out Port for yourself 

Custom Github App

This page details how to install Port's GitHub integration using a custom GitHub App, which provides automatic access token rotation.

This page outlines the following steps:

  1. How to create a new app in your GitHub organization;
  2. How to install the GitHub app in your GitHub organization and select repositories.
  3. How to deploy the integration in the configuration that fits your use case.

Prerequisites​

  • A GitHub account with permissions to create and manage GitHub Apps in your organization. This typically requires being an Organization Owner or having the "App Manager" role.
  • Your Port user role is set to Admin.

Create a GitHub app​

  1. Navigate to your Github organization and click on Settings:

Org view

  1. Inside the settings view, click on Developer Settings -> and then select GitHub Apps:

Settings view

  1. Click on "New GitHub App":

New GitHub App

  1. Insert the following properties:
  • GitHub App name: Choose a unique name for the app. Note that GitHub App names must be globally unique.
  • Homepage URL: https://port.io
  • Callback URL: Leave this empty.
  • Setup URL: Leave this empty.
  • Uncheck Active under Webhooks. The integration will automatically create the webhook if you configure the OCEAN__BASE_URL variable later during deployment.
  • Repository Permissions:
    • Checks: Readonly (for syncing Port.yml).
    • Contents: Readonly (for reading port configuration files and repository files).
    • Metadata: Readonly.
    • Pull Request: Readonly
  • Organization Permissions:
    • Webhooks: Read and Write (to allow the integration create webhook).

Then select "Create GitHub App"

  1. Go to the Private keys at the bottom of the General settings page:

Generate Private key

Keep the file, you will need it for the deployment step.

Installing GitHub App​

After you have the app registered in your organization, you can install it and select the repositories to integrate it with:

  1. First, navigate to your organization and click on Settings:

Org view

  1. Inside the settings view, click on Developer Settings -> and then select GitHub Apps:

Settings view

  1. Click edit on the GitHub app created at the step before:

GitHub integration installation page

  1. Go to Install App -> and select the installation button on your wanted organization;

  2. Choose the repositories you want the integration to be installed for:

GitHub integration installation chooses repositories

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_APP_ID="<GITHUB_APP_ID>" \ # client id also works
-e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_PRIVATE_KEY="<BASE_64_ENCODED_PRIVATEKEY>" \
-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.

base64 encoding

On MacOS and Linux you can get base64 encoded private key by using:

base64 -i <path/to/downloaded/private_key.pem>

You can accomplish the same on Windows using Powershell:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("path\to\downloaded\private_key.pem"))

Online: https://www.base64encode.org/

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_APP_IDApp id or client id. You can find it in the edit GitHub app page.✅
OCEAN__INTEGRATION__CONFIG__GITHUB_APP_PRIVATE_KEYA base64 encoded Github app private key.✅
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.

Self-Service Actions

To use Self-Service Actions with GitHub Workflows, you need to install our public GitHub Cloud App.