Configure GitHub App for Plane integration

This guide walks you through setting up a GitHub App to enable GitHub integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for GitHub, you’ll need to set up the necessary authentication, permissions, and webhooks to ensure smooth integration.

In this guide, you’ll:

1. Create and configure a GitHub App
2. Set up permissions and events
3. Configure your Plane instance

​

Create GitHub App

To configure GitHub integration, you’ll need to create a GitHub App within your organization. Follow these steps:

1. Go to Settings > Developer Settings > GitHub Apps in your GitHub organization.

2. Click New GitHub App.

3. In the Register new GitHub App page, provide a GitHub App name and Homepage URL.

4. In the Identifying and authorizing users section, add the following Callback URLS.

   https://<your-domain>/silo/api/github/auth/callback
   https://<your-domain>/silo/api/github/auth/user/callback
   

   These URLs allow Plane to verify and enable workspace connection with the Github App.

5. In the Post installation section, add the below Setup URL.

   https://<your-domain>/silo/api/github/auth/callback
   

   Redirects users to this URL after GitHub app installation.

6. Turn on Redirect on update.

7. In the Webhook section, add the below Webhook URL.

   https://<your-domain>/silo/api/github/github-webhook
   

   This allows Plane to receive updates from GitHub repositories.

​

Set up permissions and events

1. Add repository and account permissions by setting the Access dropdown next to each permission, as shown in the tables below.

   Repository permissions

   Permission	Access level	Purpose
   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).
   Contents	Read and write	Grants access to read and modify repository contents, including reading files, creating commits, and updating files.
   Issues	Read and write	Enables reading, creating, updating, closing, and commenting on issues within the repository.
   Merge queues	Read-only	Allows interaction with merge queues to manage the order of pull request merges.
   Metadata	Read-only	Provides read-only access to repository metadata, such as its name, description, and visibility.
   Pull requests	Read and write	Allows reading, creating, updating, merging, and commenting on pull requests.

   Account permissions

   Permission	Access level	Purpose
   Email addresses	Read-only	Grants access to users’ email addresses, typically for notifications or communication.
   Profile	Read and write	Enables access to user profile details like name, username, and avatar.

2. In the Subscribe to events section, turn on all the required events below.

   Event	Purpose
   Installation target	This is where the repositories or organizations where your GitHub App is installed. This determines which repositories Plane can sync with.
   Meta	Includes metadata about the app’s configuration and setup. This is essential for maintaining integration stability.
   Issue comment	Triggers when a comment is added, edited, or deleted on an issue. Useful for keeping comments synced between Plane and GitHub.
   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.
   Pull request	Fires when a pull request is opened, closed, merged, edited, or labeled. Essential for tracking development progress.
   Pull request review	Activates when a review is submitted, edited, or dismissed. Keeps review activities aligned between Plane and GitHub.
   Pull request review comment	Fires when a review comment is added, modified, or removed. Ensures feedback is reflected across both platforms.
   Pull request review thread	Triggers when a review discussion thread is resolved or reopened. Helps maintain visibility on code review discussions.
   Push	Activates when new commits are pushed to a repository. Useful for tracking code updates and changes.
   Repository sub issues	Tracks issues within a repository that are linked to or managed by another issue. Ensures accurate synchronization of related issues.

3. Click the Create GitHub App button at the bottom of the page.

​

Configure Plane instance

1. Go back to Settings > Developer Settings > GitHub Apps.

2. Click Edit on the GitHub you created.

3. In the General tab, under the Client secrets section, click Generate a new client secret.

4. Scroll down to the Private keys section.

5. Click Genereate a private key.

6. Retrieve the following details from the General tab:

   • App ID
   • Client ID
   • Client secret
   • GitHub App name
   • Private key

7. Before adding the Private key as an environment variable, you’ll need 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:

   cat private_key.pem | base64 -w 0
   

8. Add these environment variables with the values to your Plane instance’s .env file.

   GITHUB_CLIENT_ID=<client_id>
   GITHUB_CLIENT_SECRET=<client_secret>
   GITHUB_APP_NAME=<app_name>
   GITHUB_APP_ID=<app_id>
   GITHUB_PRIVATE_KEY=<private_key>
   

9. Save the file and restart the instance.

10. Once you’ve completed the instance configuration, activate the GitHub integration in Plane.