Github App

Prerequisites

• A registered organization in Port;
• Your Port user role is set to Admin.

In organizations that have a self-hosted GitHub installation there is no access to our official public app, therefore there are some extra steps you need to take to install the GitHub integration:

1. Register Port's GitHub integration in your GitHub organization;
2. Deploy Port's GitHub integration Docker image inside your VPC;
3. Install Port's GitHub integration in your GitHub organization and on select repositories.

Register Port's GitHub integration

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

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

3. Click on "New GitHub App":

4. Insert the following properties:

• GitHub App name: port.io
• Homepage URL: https://getport.io
• Repository Permissions:
  • Actions: Read and Write (for executing self-service action using GitHub workflow)
  • Checks: Read and Write (for validating Port.yml)
  • Contents: Readonly (for reading port configuration files and repository files)
  • Metadata: Readonly
  • Pull Request: Read and Write
• Organization Permissions:
  • Webhooks: Read and Write (to allow the integration create webhooks)
• Repository Events (required to receive webhook changes from GitHub):
  • Pull Request
  • Push

Then select "Create GitHub App"

5. Go to the settings of the created GitHub app and generate a private key. Save the downloaded file:

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

Deployment

Prerequisites

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:

In order to make use of Self-Service Actions using GitHub Workflow, please contact us at support@getport.io.

Installing Port's GitHub integration

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:

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

3. Click edit on the GitHub integration created at the step before:

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

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

Docker

To use our GitHub integration as an app, you will need to deploy our official integration Docker image - providing an app id and an app private key.

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:latest

Run the following command to start the app:

docker run \
  -e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_ID=<Github APP ID> \
  -e OCEAN__INTEGRATION__CONFIG__WEBHOOK_SECRET="test" \
  -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST=<GH BASE URL ie github.compay.com> \
  -e OCEAN__BASE_URL=https://test.com \
  -e OCEAN__PORT__BASE_URL=https://api.getport.io \
  -e OCEAN__PORT__CLIENT_ID=<PORT CLIENT ID> \
  -e OCEAN__PORT__CLIENT_SECRET=<PORT CLIENT SECRET> \
  -e OCEAN__INTEGRATION__IDENTIFIER=github-ocean \
  -e OCEAN__EVENT_LISTENER__TYPE=POLLING \
  -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=<Github Organization> \
  -e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_PRIVATE_KEY=<BASE 64 PRIVATEKEY> \
  -p 8000:8000 \
  ghcr.io/port-labs/port-ocean-github-ocean:latest

Env variable	Description
OCEAN__INTEGRATION__CONFIG__GITHUB_APP_ID	Application ID. You can find it in the edit GitHub app page.
OCEAN__INTEGRATION__CONFIG__WEBHOOK_SECRET	Will be used to create webhook
OCEAN__INTEGRATION__IDENTIFIER	Your organization's self-hosted GitHub hostname
OCEAN__BASE_URL	Integration base url, will be used to register webhook.
OCEAN__PORT__BASE_URL	Port's API Base URL
OCEAN__PORT__CLIENT_ID	Port client id for interacting with the API
OCEAN__PORT__CLIENT_SECRET	Port client secret for interacting with the API
OCEAN__INTEGRATION__IDENTIFIER	Identifier for the integration
OCEAN__EVENT_LISTENER__TYPE	How Ocean will retrieve config changes from Port.
OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION	The GitHub organization the integration was installed in.
OCEAN__INTEGRATION__CONFIG__GITHUB_APP_PRIVATE_KEY	A base64 encoded Github app private key. You can use a tool like https://www.base64encode.org/