Self Hosted Installation

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

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
• Setup URL: https://app.getport.io
• 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"

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

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

Deployment

Prerequisites

You will need your Port ORG_ID, 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.

Docker

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 ghcr.io/port-labs/port-self-hosted-github-app:0.15.0

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 GHE_HOST=<GITHUB BASE HOST, ie github.compay.com> \
  -e PORT=<Any PORT> \
  -e PORT_URL=https://api.getport.io \
  -e PORT_ORG_ID=<ORG_ID> \
  -e PORT_CLIENT_ID=<CLIENT_ID> \
  -e PORT_CLIENT_SECRET=<CLIENT_SECRET> \
  -e PRIVATE_KEY=<BASE 64 PRIVATEKEY> \
  -p <PORT>:<PORT> \
  ghcr.io/port-labs/port-self-hosted-github-app:0.15.0

Env variable	Description
APP_ID	Application ID, you can find it in the edit GitHub App page
WEBHOOK_SECRET	The same string that was used to register the application in the previous step
GHE_HOST	Your organization's self-hosted GitHub hostname
PORT	The port that the GitHub App will listen to
PORT_URL	Port's API Base URL
PORT_ORG_ID	Your Port org id
PORT_CLIENT_ID	Port client id for interacting with the API
PORT_CLIENT_SECRET	Port client secret for interacting with the API
PRIVATE_KEY	A base64 encoded private key. You can use a tool like https://www.base64encode.org/

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:

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

3. Click edit on the GitHub app 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 app to be installed for:

Limitations

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;