Skip to main content

Self Hosted Installation

  • 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 app:

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

Register Port's GitHub Appโ€‹

  1. Navigate to your organization inside your self-hosted GitHub 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:
  • Homepage URL:
  • Setup URL:
  • Webhook URL: HTTP Server URL, if you don't yet know the value of this step, leave it blank until you deploy the GitHub backend
  • Webhook secret: Webhook secret (Any string you would like)
  • 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
    • Issues: Readonly
    • Pull Request: Read and Write
    • Dependabot alerts: Readonly
    • Administration: Readonly (for syncing github teams)
  • Organization Permissions:
    • Members: Readonly (for syncing github teams)
  • Repository Events (required to receive webhook changes from GitHub):
    • Issues
    • Pull Request
    • Push
    • Workflow Run
    • Team
    • Dependabot alerts

Then select "Create GitHub App"

  1. Go to the settings of the created GitHub App and generate a private key and save the downloaded file:

Generate Private key

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



You will need your Port CLIENT_ID and CLIENT_SECRET.

To get your Port API credentials go to your Port application, hover over 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


To use our GitHub app you will need to deploy our official GitHub app docker image on your VPC.

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

Run the following command to start the app:

docker run \
-e APP_ID=<APP_ID from register step> \
-e WEBHOOK_SECRET=<WEBHOOK_SECRET from previous step> \
-e PORT=<Any PORT> \
-e PORT_URL= \
-p <PORT>:<PORT> \
Env variableDescription
APP_IDApplication ID, you can find it in the edit GitHub App page
WEBHOOK_SECRETThe same string that was used to register the application in the previous step
GHE_HOSTYour organization's self-hosted GitHub hostname
PORTThe port that the GitHub App will listen to
PORT_CLIENT_IDPort client id for interacting with the API
PORT_CLIENT_SECRETPort client secret for interacting with the API
PRIVATE_KEYA base64 encoded private key. You can use a tool like

Health check routeโ€‹

A health check is a route that is used to check the health of a service. It is a means to ensure that the service is running properly and can perform its intended function.

Our GitHub App image exposes a health check route at https://host:port/health to monitor its status.

Installing Port's GitHub applicationโ€‹

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

  1. First, navigate to your organization inside your self-hosted GitHub 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 app installation page

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

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

GitHub app installation chooses repositories


As this is a self-hosted version, there are some limitations due to security considerations and the fact that we don't have access to your GitHub instance

  • You must include configuration as part of the repository, and you can't configure it via Port's UI/API;

  • To use self-service actions, you will need Kafka Credentials configured for your organization;