-
Notifications
You must be signed in to change notification settings - Fork 11
[DOCSW-443] Github Enterprise App Create Dev Docs #127
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.
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
Merged
Merged
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| --- | ||
| title : Configure GitHub Enterprise App for Plane integration | ||
| sidebarTitle: Github Enterprise | ||
| --- | ||
|
|
||
| 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. | ||
|
|
||
| In this guide, you’ll: | ||
| 1. [Create and configure a GitHub App](/self-hosting/govern/integrations/github#create-github-app) | ||
| 2. [Set up permissions and events](/self-hosting/govern/integrations/github#set-up-permissions-and-events) | ||
| 3. [Configure your Plane instance](/self-hosting/govern/integrations/github#configure-plane-instance) | ||
|
|
||
| <Warning> | ||
| **Activate GitHub integration** | ||
|
|
||
| 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. | ||
| </Warning> | ||
|
|
||
| ## Create GitHub App | ||
|
|
||
| To configure GitHub Enterprise 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**. | ||
|
|
||
| ```bash | ||
| https://<your-plane-domain>/silo/api/oauth/github-enterprise/auth/callback | ||
| https://<your-plane-domain>/silo/api/oauth/github-enterprise/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**. | ||
|
|
||
| ```bash | ||
| https://<your-plane-domain>/silo/api/oauth/github-enterprise/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**. | ||
| ```bash | ||
| https://<your-plane-domain>/silo/api/github-enterprise/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 **Generate a private key**. | ||
|
|
||
| 6. Retrieve the following details from the **General** tab: | ||
| - App ID | ||
| - App Slug (You can find this in browser url) | ||
| - Client ID | ||
| - Client secret | ||
| - Private key | ||
|
|
||
| 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: | ||
| ```bash | ||
| cat private_key.pem | base64 -w 0 | ||
| ``` | ||
|
|
||
| 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). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Internal links point to the standard GitHub guide, not this Enterprise guide
The step list links (
…/integrations/github#…) will take readers away from the Enterprise page. Update the slug togithub-enterpriseso anchors resolve locally.📝 Committable suggestion
🤖 Prompt for AI Agents