From a63d49ea5cf97a4fb81420ac5df59dc2b7fc4db8 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Tue, 26 Aug 2025 23:30:06 +0000 Subject: [PATCH] Update self-hosted GitHub installation documentation to clarify prerequisites, registration steps, and deployment instructions. Improved formatting and added images for better guidance. --- .../git/github/self-hosted-installation.md | 113 +++++++++--------- 1 file changed, 57 insertions(+), 56 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation.md index 9d0d3189d4..ae6edf6bf6 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation.md @@ -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. + -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) + 2. Inside the settings view, click on Developer Settings -> and then select GitHub Apps: -![Settings view](../../../../../static/img/integrations/github-app/SelfHostedOrganizationSettings.png) + 3. Click on "New GitHub App": -![New GitHub App](../../../../../static/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 - + 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 -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. @@ -97,13 +98,13 @@ Run the following command to start the app: docker run \ -e APP_ID= \ -e WEBHOOK_SECRET= \ - -e GHE_HOST= \ + -e GHE_HOST= \ -e PORT= \ - -e PORT_URL=https://api.getport.io \ - -e PORT_ORG_ID= \ #For self service actions, requires a Kafka topic + -e PORT_API_URL=https://api.getport.io \ + -e PORT_ORG_ID= \ -e PORT_CLIENT_ID= \ -e PORT_CLIENT_SECRET= \ - -e PRIVATE_KEY= \ + -e PRIVATE_KEY= \ -p : \ ghcr.io/port-labs/port-self-hosted-github-app:0.16.7 ``` @@ -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/ | @@ -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) + 2. Inside the settings view, click on Developer Settings -> and then select GitHub Apps: -![Settings view](../../../../../static/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) + 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) + ## Limitations