Skip to content

PORT-11992 Bug Updated self-hosted GitHub installation documentation #2723

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

PORT-11992 Bug Updated self-hosted GitHub installation documentation #2723

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a63d49e
Update self-hosted GitHub installation documentation to clarify prere…
kodjomiles Aug 26, 2025
ab4318c
Merge branch 'main' into PORT-11992-bug-doc-for-github-enterprise-on-…
kodjomiles Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 57 additions & 56 deletions ...ur-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,80 +6,81 @@ import FindCredentials from "/docs/build-your-software-catalog/custom-integratio

# Self Hosted Installation

:::note Prerequisites
The "Self Hosted Installation" guide is specifically for organizations that run their own GitHub Enterprise instance.

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

## Prerequisites

:::
- Completed [Port onboarding process](https://docs.port.io/getting-started/overview).
- Your Port user role is set to `Admin`.
- Port Client ID, Client Secret, and Org ID.
<FindCredentials/>

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

1. [Register](#register-ports-github-app) Port's GitHub app in your GitHub organization;
2. [Deploy](#deployment) Port's GitHub app Docker image inside your VPC;
1. [Register](#register-ports-github-app) Port's GitHub app in your GitHub organization.
2. [Deploy](#deployment) Port's GitHub app Docker image inside your VPC.
3. [Install](#installing-ports-github-application) Port's GitHub app in your GitHub organization and on select repositories.

## Register Port's GitHub App
### Register Port's GitHub App

1. Navigate to your organization inside your self-hosted GitHub and click on Settings:

![Org view](../../../../../static/img/integrations/github-app/SelfHostedOrganizaionView.png)
<img src="/img/integrations/github-app/SelfHostedOrganizaionView.png"/>

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

![Settings view](../../../../../static/img/integrations/github-app/SelfHostedOrganizationSettings.png)
<img src="/img/integrations/github-app/SelfHostedOrganizationSettings.png"/>

3. Click on "New GitHub App":

![New GitHub App](../../../../../static/img/integrations/github-app/SelfHostedNewGitHubApp.png)
<img src="/img/integrations/github-app/SelfHostedNewGitHubApp.png"/>

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"
- **GitHub App name:** eg `MyPortApp` This name must be unique within the GitHub organization.

5. Go to the settings of the created GitHub App and generate a private key and save the downloaded file:
- **Homepage URL:** `https://getport.io`

![Generate Private key](../../../../../static/img/integrations/github-app/SelfHosetdGeneratePrivayKey.png)
- **Setup URL:** `https://app.getport.io`

Keep the file, you will need it for the deployment step.
- **Webhook URL (Required):** `HTTP Server URL`, if you don't yet know the value of this step, add a placeholder value until you deploy the GitHub backend

## Deployment
- **Webhook secret (Recommended):** `Webhook secret` (Any string you would like)

:::note Prerequisites
- **Repository Permissions:**

You will need your Port `ORG_ID`, `CLIENT_ID` and `CLIENT_SECRET`.
- 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):
- Pull Request
- Push
- Workflow Run
- Team
- Dependabot alerts

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

<img src="/img/integrations/github-app/SelfHosetdGeneratePrivayKey.png"/>

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

:::
### Deployment

In order to make use of [Self-Service Actions using GitHub Workflow](../../../../actions-and-automations/setup-backend/github-workflow/github-workflow.md), please contact us at [support.port.io](http://support.port.io/).
In order to make use of [Self-Service Actions using GitHub Workflow](https://docs.port.io/actions-and-automations/setup-backend/github-workflow), please contact us at [support.port.io](http://support.port.io/).

## Docker
### Docker

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

Expand All @@ -97,13 +98,13 @@ 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 GHE_HOST=<GITHUB BASE HOST, ie github.company.com> \
-e PORT=<Any PORT> \
-e PORT_URL=https://api.getport.io \
-e PORT_ORG_ID=<ORG_ID> \ #For self service actions, requires a Kafka topic
-e PORT_API_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> \
-e PRIVATE_KEY=<BASE 64 PRIVATEKEY> \
-p <PORT>:<PORT> \
ghcr.io/port-labs/port-self-hosted-github-app:0.16.7
```
Expand All @@ -114,8 +115,8 @@ docker run \
| `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 (For self service actions, requires a Kafka topic) |
| `PORT_API_URL` | Port's API Base URL |
| `PORT_ORG_ID` | Your Port org id (Used for [self service actions](/actions-and-automations/setup-backend/webhook/kafka/kafka.md)) |
| `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/ |
Expand All @@ -132,21 +133,21 @@ After you have the app registered in your organization and the Docker is up and

1. First, navigate to your organization inside your self-hosted GitHub and click on Settings:

![Org view](../../../../../static/img/integrations/github-app/SelfHostedOrganizaionView.png)
<img src="/img/integrations/github-app/SelfHostedOrganizaionView.png" />

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

![Settings view](../../../../../static/img/integrations/github-app/SelfHostedOrganizationSettings.png)
<img src="/img/integrations/github-app/SelfHostedOrganizationSettings.png" />

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

![GitHub app installation page](../../../../../static/img/integrations/github-app/SelfHostedEditGitHubApp.png)
<img src="/img/integrations/github-app/SelfHostedEditGitHubApp.png" />

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:

![GitHub app installation chooses repositories](../../../../../static/img/integrations/github-app/SelfHostedInstallationRepoSelection.png)
<img src="/img/integrations/github-app/SelfHostedInstallationRepoSelection.png" />

## Limitations

Expand Down