|
| 1 | +--- |
| 2 | +title : Configure GitHub Enterprise App for Plane integration |
| 3 | +sidebarTitle: Github Enterprise |
| 4 | +--- |
| 5 | + |
| 6 | +This guide walks you through setting up a GitHub App to enable GitHub Enterprise integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for GitHub Enterprise, you’ll need to set up the necessary authentication, permissions, and webhooks to ensure smooth integration. |
| 7 | + |
| 8 | +In this guide, you’ll: |
| 9 | +1. [Create and configure a GitHub App](/self-hosting/govern/integrations/github#create-github-app) |
| 10 | +2. [Set up permissions and events](/self-hosting/govern/integrations/github#set-up-permissions-and-events) |
| 11 | +3. [Configure your Plane instance](/self-hosting/govern/integrations/github#configure-plane-instance) |
| 12 | + |
| 13 | +<Warning> |
| 14 | +**Activate GitHub integration** |
| 15 | + |
| 16 | +After creating and configuring the GitHub app you'll need to [setup the GitHub Enterprise integration](https://docs.plane.so/integrations/github-enterprise) within Plane. |
| 17 | +</Warning> |
| 18 | + |
| 19 | +## Create GitHub App |
| 20 | + |
| 21 | +To configure GitHub Enterprise integration, you'll need to create a GitHub App within your organization. Follow these steps: |
| 22 | + |
| 23 | +1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization. |
| 24 | + |
| 25 | +2. Click **New GitHub App**. |
| 26 | +  |
| 27 | + |
| 28 | +3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**. |
| 29 | +  |
| 30 | + |
| 31 | +4. In the **Identifying and authorizing users** section, add the following **Callback URLS**. |
| 32 | + |
| 33 | + ```bash |
| 34 | + https://<your-plane-domain>/silo/api/oauth/github-enterprise/auth/callback |
| 35 | + https://<your-plane-domain>/silo/api/oauth/github-enterprise/auth/user/callback |
| 36 | + ``` |
| 37 | + These URLs allow Plane to verify and enable workspace connection with the Github App. |
| 38 | +  |
| 39 | + |
| 40 | +5. In the **Post installation** section, add the below **Setup URL**. |
| 41 | + |
| 42 | + ```bash |
| 43 | + https://<your-plane-domain>/silo/api/oauth/github-enterprise/auth/callback |
| 44 | + ``` |
| 45 | + Redirects users to this URL after GitHub app installation. |
| 46 | +  |
| 47 | + |
| 48 | +6. Turn on **Redirect on update**. |
| 49 | + |
| 50 | +7. In the **Webhook** section, add the below **Webhook URL**. |
| 51 | + ```bash |
| 52 | + https://<your-plane-domain>/silo/api/github-enterprise/github-webhook |
| 53 | + ``` |
| 54 | + This allows Plane to receive updates from GitHub repositories. |
| 55 | + |
| 56 | +  |
| 57 | + |
| 58 | +### Set up permissions and events |
| 59 | + |
| 60 | +1. Add repository and account permissions by setting the **Access** dropdown next to each permission, as shown in the tables below. |
| 61 | +  |
| 62 | + |
| 63 | + **Repository permissions** |
| 64 | + |
| 65 | + |Permission |Access level |Purpose| |
| 66 | + |---------|---------------------|-----------| |
| 67 | + |Commit statuses|Read-only|Allows the GitHub app to read and update commit statuses, indicating whether a commit has passed checks (e.g., CI/CD pipelines).| |
| 68 | + |Contents|Read and write|Grants access to read and modify repository contents, including reading files, creating commits, and updating files.| |
| 69 | + |Issues|Read and write|Enables reading, creating, updating, closing, and commenting on issues within the repository.| |
| 70 | + |Merge queues|Read-only|Allows interaction with merge queues to manage the order of pull request merges.| |
| 71 | + |Metadata|Read-only|Provides read-only access to repository metadata, such as its name, description, and visibility.| |
| 72 | + |Pull requests|Read and write|Allows reading, creating, updating, merging, and commenting on pull requests.| |
| 73 | + |
| 74 | + **Account permissions** |
| 75 | + |
| 76 | + |Permission |Access level |Purpose| |
| 77 | + |---------|------------|-----------| |
| 78 | + |Email addresses|Read-only|Grants access to users' email addresses, typically for notifications or communication.| |
| 79 | + |Profile|Read and write|Enables access to user profile details like name, username, and avatar.| |
| 80 | + |
| 81 | + |
| 82 | +2. In the **Subscribe to events** section, turn on all the required events below. |
| 83 | + |
| 84 | +  |
| 85 | + |
| 86 | + |Event |Purpose| |
| 87 | + |---------|------------| |
| 88 | + |Installation target| This is where the repositories or organizations where your GitHub App is installed. This determines which repositories Plane can sync with.| |
| 89 | + |Meta|Includes metadata about the app's configuration and setup. This is essential for maintaining integration stability.| |
| 90 | + |Issue comment| Triggers when a comment is added, edited, or deleted on an issue. Useful for keeping comments synced between Plane and GitHub.| |
| 91 | + |Issues|Triggers when an issue is created, updated, closed, reopened, assigned, labeled, or transferred. Ensures issue status and details remain consistent between Plane and GitHub.| |
| 92 | + |Pull request|Fires when a pull request is opened, closed, merged, edited, or labeled. Essential for tracking development progress.| |
| 93 | + |Pull request review|Activates when a review is submitted, edited, or dismissed. Keeps review activities aligned between Plane and GitHub.| |
| 94 | + |Pull request review comment|Fires when a review comment is added, modified, or removed. Ensures feedback is reflected across both platforms.| |
| 95 | + |Pull request review thread|Triggers when a review discussion thread is resolved or reopened. Helps maintain visibility on code review discussions.| |
| 96 | + |Push|Activates when new commits are pushed to a repository. Useful for tracking code updates and changes.| |
| 97 | + |Repository sub issues|Tracks issues within a repository that are linked to or managed by another issue. Ensures accurate synchronization of related issues.| |
| 98 | + |
| 99 | +3. Click the **Create GitHub App** button at the bottom of the page. |
| 100 | + |
| 101 | +## Configure Plane instance |
| 102 | + |
| 103 | +1. Go back to **Settings \> Developer Settings \> GitHub Apps**. |
| 104 | + |
| 105 | +2. Click **Edit** on the GitHub you created. |
| 106 | + |
| 107 | +3. In the **General** tab, under the **Client secrets** section, click **Generate a new client secret**. |
| 108 | + |
| 109 | +  |
| 110 | + |
| 111 | +4. Scroll down to the **Private keys** section. |
| 112 | + |
| 113 | +  |
| 114 | + |
| 115 | +5. Click **Generate a private key**. |
| 116 | + |
| 117 | +6. Retrieve the following details from the **General** tab: |
| 118 | + - App ID |
| 119 | + - App Slug (You can find this in browser url) |
| 120 | + - Client ID |
| 121 | + - Client secret |
| 122 | + - Private key |
| 123 | + |
| 124 | +7. Convert the Private key to convert it to base64. Since private keys are typically multi-line, they can cause parsing errors or issues when setting environment variables. To avoid this, run the following command to convert the key to base64: |
| 125 | + ```bash |
| 126 | + cat private_key.pem | base64 -w 0 |
| 127 | + ``` |
| 128 | + |
| 129 | +8. Once you've created the app, [activate the GitHub Enterprise integration in Plane](https://docs.plane.so/integrations/github-enterprise#connect-github-enterprise-organization). |
0 commit comments