Skip to content

Commit 3dcb171

Browse files
hadar-cohadar-co
authored
Merge pull request #2723 from port-labs/PORT-11992-bug-doc-for-github-enterprise-on-prem-is-misleading
PORT-11992 Bug Updated self-hosted GitHub installation documentation
2 parents 6afc73d + e360db0 commit 3dcb171

File tree

1 file changed

+57
-56
lines changed

1 file changed

+57
-56
lines changed

‎docs/build-your-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation.md‎

Lines changed: 57 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -6,80 +6,81 @@ import FindCredentials from "/docs/build-your-software-catalog/custom-integratio
66

77
# Self Hosted Installation
88

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

11-
- A registered organization in Port;
12-
- Your Port user role is set to `Admin`.
11+
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.
12+
13+
## Prerequisites
1314

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

16-
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:
20+
## Steps
1721

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

22-
## Register Port's GitHub App
26+
### Register Port's GitHub App
2327

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

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

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

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

3236
3. Click on "New GitHub App":
3337

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

3640
4. Insert the following properties:
3741

38-
- **GitHub App name:** port.io
39-
- **Homepage URL:** https://getport.io
40-
- **Setup URL:** https://app.getport.io
41-
- **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
42-
- **Webhook secret:** Webhook secret (Any string you would like)
43-
- **Repository Permissions:**
44-
- Actions: Read and Write (for executing self-service action using GitHub workflow)
45-
- Checks: Read and Write (for validating `Port.yml`)
46-
- Contents: Readonly (for reading port configuration files and repository files)
47-
- Metadata: Readonly
48-
- Issues: Readonly
49-
- Pull Request: Read and Write
50-
- Dependabot alerts: Readonly
51-
- Administration: Readonly (for syncing github teams)
52-
- **Organization Permissions:**
53-
- Members: Readonly (for syncing github teams)
54-
- **Repository Events** (required to receive webhook changes from GitHub):
55-
- Issues
56-
- Pull Request
57-
- Push
58-
- Workflow Run
59-
- Team
60-
- Dependabot alerts
61-
62-
Then select "Create GitHub App"
42+
- **GitHub App name:** eg `MyPortApp` This name must be unique within the GitHub organization.
6343

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

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

68-
Keep the file, you will need it for the deployment step.
48+
- **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
6949

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

72-
:::note Prerequisites
52+
- **Repository Permissions:**
7353

74-
You will need your Port `ORG_ID`, `CLIENT_ID` and `CLIENT_SECRET`.
54+
- Actions: Read and Write (for executing self-service action using GitHub workflow)
55+
- Checks: Read and Write (for validating `Port.yml`)
56+
- Contents: Readonly (for reading port configuration files and repository files)
57+
- Metadata: Readonly
58+
- Issues: Readonly
59+
- Pull Request: Read and Write
60+
- Dependabot alerts: Readonly
61+
- Administration: Readonly (for syncing github teams)
62+
- **Organization Permissions:**
63+
- Members: Readonly (for syncing github teams)
64+
- **Repository Events** (required to receive webhook changes from GitHub):
65+
- Pull Request
66+
- Push
67+
- Workflow Run
68+
- Team
69+
- Dependabot alerts
7570

76-
<FindCredentials/>
71+
Then select `Create GitHub App`.
72+
73+
5. Go to the settings of the created GitHub App and generate a private key and save the downloaded file:
74+
75+
<img src="/img/integrations/github-app/SelfHosetdGeneratePrivayKey.png"/>
76+
77+
Keep the file, you will need it for the deployment step.
7778

78-
:::
79+
### Deployment
7980

80-
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/).
81+
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/).
8182

82-
## Docker
83+
### Docker
8384

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

@@ -97,13 +98,13 @@ Run the following command to start the app:
9798
docker run \
9899
-e APP_ID=<APP_ID from register step> \
99100
-e WEBHOOK_SECRET=<WEBHOOK_SECRET from previous step> \
100-
-e GHE_HOST=<GITHUB BASE HOST, ie github.compay.com> \
101+
-e GHE_HOST=<GITHUB BASE HOST, ie github.company.com> \
101102
-e PORT=<Any PORT> \
102-
-e PORT_URL=https://api.getport.io \
103-
-e PORT_ORG_ID=<ORG_ID> \ #For self service actions, requires a Kafka topic
103+
-e PORT_API_URL=https://api.getport.io \
104+
-e PORT_ORG_ID=<ORG_ID> \
104105
-e PORT_CLIENT_ID=<CLIENT_ID> \
105106
-e PORT_CLIENT_SECRET=<CLIENT_SECRET> \
106-
-e PRIVATE_KEY=<BASE 64 PRIVATEKEY> \
107+
-e PRIVATE_KEY=<BASE 64 PRIVATEKEY> \
107108
-p <PORT>:<PORT> \
108109
ghcr.io/port-labs/port-self-hosted-github-app:0.16.7
109110
```
@@ -114,8 +115,8 @@ docker run \
114115
| `WEBHOOK_SECRET` | The same string that was used to register the application in the previous step |
115116
| `GHE_HOST` | Your organization's self-hosted GitHub hostname |
116117
| `PORT` | The port that the GitHub App will listen to |
117-
| `PORT_URL` | Port's API Base URL |
118-
| `PORT_ORG_ID` | Your Port org id (For self service actions, requires a Kafka topic) |
118+
| `PORT_API_URL` | Port's API Base URL |
119+
| `PORT_ORG_ID` | Your Port org id (Used for [self service actions](/actions-and-automations/setup-backend/webhook/kafka/kafka.md)) |
119120
| `PORT_CLIENT_ID` | Port client id for interacting with the API |
120121
| `PORT_CLIENT_SECRET` | Port client secret for interacting with the API |
121122
| `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
132133

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

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

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

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

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

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

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

147148
5. Choose the repositories you want the app to be installed for:
148149

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

151152
## Limitations
152153

0 commit comments

Comments
 (0)