From 77a7d77c5b5c02806bfffb343d3182377d1e37bb Mon Sep 17 00:00:00 2001 From: Saurabhkmr98 Date: Wed, 30 Jul 2025 20:18:32 +0530 Subject: [PATCH 1/2] added dev docs for github enterprise app creation --- mint.json | 3 +- .../govern/integrations/github-enterprise.mdx | 129 ++++++++++++++++++ self-hosting/govern/integrations/github.mdx | 2 +- 3 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 self-hosting/govern/integrations/github-enterprise.mdx diff --git a/mint.json b/mint.json index 5a101da1..fbc71488 100644 --- a/mint.json +++ b/mint.json @@ -101,7 +101,8 @@ "pages": [ "self-hosting/govern/integrations/github", "self-hosting/govern/integrations/slack", - "self-hosting/govern/integrations/gitlab" + "self-hosting/govern/integrations/gitlab", + "self-hosting/govern/integrations/github-enterprise" ] }, "self-hosting/govern/external-secrets", diff --git a/self-hosting/govern/integrations/github-enterprise.mdx b/self-hosting/govern/integrations/github-enterprise.mdx new file mode 100644 index 00000000..d468a986 --- /dev/null +++ b/self-hosting/govern/integrations/github-enterprise.mdx @@ -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) + + +**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. + + +## 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**. + ![Create GitHub App](/images/integrations/github/create-github-app.webp) + +3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**. + ![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp) + +4. In the **Identifying and authorizing users** section, add the following **Callback URLS**. + + ```bash + https:///silo/api/oauth/github-enterprise/auth/callback + https:///silo/api/oauth/github-enterprise/auth/user/callback + ``` + These URLs allow Plane to verify and enable workspace connection with the Github App. + ![Add Callback URL](/images/integrations/github/add-callback-url.webp) + +5. In the **Post installation** section, add the below **Setup URL**. + + ```bash + https:///silo/api/oauth/github-enterprise/auth/callback + ``` + Redirects users to this URL after GitHub app installation. + ![Add setup URL](/images/integrations/github/add-setup-url.webp) + +6. Turn on **Redirect on update**. + +7. In the **Webhook** section, add the below **Webhook URL**. + ```bash + https:///silo/api/github-enterprise/github-webhook + ``` + This allows Plane to receive updates from GitHub repositories. + + ![Add Webhook URL](/images/integrations/github/add-webhook-url.webp) + +### 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. + ![Setup permissions](/images/integrations/github/setup-permissions.webp) + + **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. + + ![Subscribe to events](/images/integrations/github/subscribe-to-events.webp) + + |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**. + + ![General tab](/images/integrations/github/general-tab.webp) + +4. Scroll down to the **Private keys** section. + + ![Private keys](/images/integrations/github/private-keys.webp) + +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). \ No newline at end of file diff --git a/self-hosting/govern/integrations/github.mdx b/self-hosting/govern/integrations/github.mdx index 7a1a8443..25efcdd2 100644 --- a/self-hosting/govern/integrations/github.mdx +++ b/self-hosting/govern/integrations/github.mdx @@ -112,7 +112,7 @@ To configure GitHub integration, you'll need to create a GitHub App within your ![Private keys](/images/integrations/github/private-keys.webp) -5. Click **Genereate a private key**. +5. Click **Generate a private key**. 6. Retrieve the following details from the **General** tab: - App ID From 50b04affe287d1427712441f967769ac217aa4a8 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Fri, 1 Aug 2025 19:37:39 +0530 Subject: [PATCH 2/2] Merge both into one and created tabbed sections --- mint.json | 3 +- .../govern/integrations/github-enterprise.mdx | 129 ------------ self-hosting/govern/integrations/github.mdx | 197 ++++++++++++++---- 3 files changed, 158 insertions(+), 171 deletions(-) delete mode 100644 self-hosting/govern/integrations/github-enterprise.mdx diff --git a/mint.json b/mint.json index 54ed7dbd..e831fc5b 100644 --- a/mint.json +++ b/mint.json @@ -101,8 +101,7 @@ "pages": [ "self-hosting/govern/integrations/github", "self-hosting/govern/integrations/slack", - "self-hosting/govern/integrations/gitlab", - "self-hosting/govern/integrations/github-enterprise" + "self-hosting/govern/integrations/gitlab" ] }, "self-hosting/govern/external-secrets", diff --git a/self-hosting/govern/integrations/github-enterprise.mdx b/self-hosting/govern/integrations/github-enterprise.mdx deleted file mode 100644 index d468a986..00000000 --- a/self-hosting/govern/integrations/github-enterprise.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -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) - - -**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. - - -## 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**. - ![Create GitHub App](/images/integrations/github/create-github-app.webp) - -3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**. - ![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp) - -4. In the **Identifying and authorizing users** section, add the following **Callback URLS**. - - ```bash - https:///silo/api/oauth/github-enterprise/auth/callback - https:///silo/api/oauth/github-enterprise/auth/user/callback - ``` - These URLs allow Plane to verify and enable workspace connection with the Github App. - ![Add Callback URL](/images/integrations/github/add-callback-url.webp) - -5. In the **Post installation** section, add the below **Setup URL**. - - ```bash - https:///silo/api/oauth/github-enterprise/auth/callback - ``` - Redirects users to this URL after GitHub app installation. - ![Add setup URL](/images/integrations/github/add-setup-url.webp) - -6. Turn on **Redirect on update**. - -7. In the **Webhook** section, add the below **Webhook URL**. - ```bash - https:///silo/api/github-enterprise/github-webhook - ``` - This allows Plane to receive updates from GitHub repositories. - - ![Add Webhook URL](/images/integrations/github/add-webhook-url.webp) - -### 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. - ![Setup permissions](/images/integrations/github/setup-permissions.webp) - - **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. - - ![Subscribe to events](/images/integrations/github/subscribe-to-events.webp) - - |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**. - - ![General tab](/images/integrations/github/general-tab.webp) - -4. Scroll down to the **Private keys** section. - - ![Private keys](/images/integrations/github/private-keys.webp) - -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). \ No newline at end of file diff --git a/self-hosting/govern/integrations/github.mdx b/self-hosting/govern/integrations/github.mdx index 25efcdd2..5c552953 100644 --- a/self-hosting/govern/integrations/github.mdx +++ b/self-hosting/govern/integrations/github.mdx @@ -5,6 +5,14 @@ sidebarTitle: GitHub 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. +This guide covers configuration for both: + +- **[GitHub Cloud](/self-hosting/govern/integrations/github?edition=github-cloud#create-github-app)** +The standard cloud-hosted GitHub service + +- **[GitHub Enterprise Server](/self-hosting/govern/integrations/github?edition=github-enterprise#create-github-app)** +Self-hosted GitHub instances for organizations with specific compliance or security requirements + 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) @@ -18,42 +26,114 @@ After creating and configuring the GitHub app and configuring the instance as de ## Create GitHub App -To configure GitHub integration, you'll need to create a GitHub App within your organization. Follow these steps: +To configure GitHub integration, you'll need to create a GitHub App within your organization. + + + + 1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization. + + 2. Click **New GitHub App**. + ![Create GitHub App](/images/integrations/github/create-github-app.webp) + + 3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**. + ![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp) + + 4. In the **Identifying and authorizing users** section, add the following **Callback URLS**. + + ```bash + https:///silo/api/github/auth/callback + https:///silo/api/github/auth/user/callback + ``` + + These URLs allow Plane to verify and enable workspace connection with the Github App. + ![Add Callback URL](/images/integrations/github/add-callback-url.webp) + +5. In the **Post installation** section, add the below **Setup URL**. + + ```bash + https:///silo/api/github/auth/callback + ``` + + Redirects users to this URL after GitHub app installation. + ![Add setup URL](/images/integrations/github/add-setup-url.webp) + + 6. Turn on **Redirect on update**. + + 7. In the **Webhook** section, add the below **Webhook URL**. + + ```bash + https:///silo/api/github/github-webhook + ``` + + This allows Plane to receive updates from GitHub repositories. + + ![Add Webhook URL](/images/integrations/github/add-webhook-url.webp) + + + 1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization. -2. Click **New GitHub App**. - ![Create GitHub App](/images/integrations/github/create-github-app.webp) + 2. Click **New GitHub App**. + ![Create GitHub App](/images/integrations/github/create-github-app.webp) -3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**. - ![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp) + 3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**. + ![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp) -4. In the **Identifying and authorizing users** section, add the following **Callback URLS**. + 4. In the **Identifying and authorizing users** section, add the following **Callback URLS**. - ```bash - https:///silo/api/github/auth/callback - https:///silo/api/github/auth/user/callback - ``` - These URLs allow Plane to verify and enable workspace connection with the Github App. - ![Add Callback URL](/images/integrations/github/add-callback-url.webp) + **For Plane cloud instance** -5. In the **Post installation** section, add the below **Setup URL**. + ```bash + https://silo.plane.so/api/github/auth/callback + https://silo.plane.so/api/github/auth/user/callback + ``` - ```bash - https:///silo/api/github/auth/callback - ``` - Redirects users to this URL after GitHub app installation. - ![Add setup URL](/images/integrations/github/add-setup-url.webp) + **For Plane self-hosted instance** -6. Turn on **Redirect on update**. + ```bash + https:///silo/api/github/auth/callback + https:///silo/api/github/auth/user/callback + ``` + + These URLs allow Plane to verify and enable workspace connection with the Github App. + ![Add Callback URL](/images/integrations/github/add-callback-url.webp) -7. In the **Webhook** section, add the below **Webhook URL**. - ```bash - https:///silo/api/github/github-webhook - ``` - This allows Plane to receive updates from GitHub repositories. + 5. In the **Post installation** section, add the below **Setup URL**. + + **For Plane cloud instance** + ```bash + https://silo.plane.so/api/oauth/github-enterprise/auth/callback + ``` + + **For Plane self-hosted instance** + + ```bash + https:///silo/api/oauth/github-enterprise/auth/callback + ``` + Redirects users to this URL after GitHub app installation. + ![Add setup URL](/images/integrations/github/add-setup-url.webp) + + 6. Turn on **Redirect on update**. + + 7. In the **Webhook** section, add the below **Webhook URL**. + + **For Plane cloud instance** + ```bash + https://silo.plane.so/api/github-enterprise/github-webhook + ``` + + **For Plane self-hosted instance** + + ```bash + https:///silo/api/github-enterprise/github-webhook + ``` + This allows Plane to receive updates from GitHub repositories. + + ![Add Webhook URL](/images/integrations/github/add-webhook-url.webp) - ![Add Webhook URL](/images/integrations/github/add-webhook-url.webp) + + ### Set up permissions and events @@ -100,6 +180,53 @@ To configure GitHub integration, you'll need to create a GitHub App within your ## 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**. + + ![General tab](/images/integrations/github/general-tab.webp) + +4. Scroll down to the **Private keys** section. + + ![Private keys](/images/integrations/github/private-keys.webp) + +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: + + ```bash + cat private_key.pem | base64 -w 0 + ``` + +8. Add these environment variables with the values to your Plane instance's `.env` file. + + ```bash + GITHUB_CLIENT_ID= + GITHUB_CLIENT_SECRET= + GITHUB_APP_NAME= + GITHUB_APP_ID= + GITHUB_PRIVATE_KEY= + ``` + +9. Save the file and restart the instance. + +10. Once you've completed the instance configuration, [activate the GitHub integration in Plane](https://docs.plane.so/integrations/github). + + + + + 1. Go back to **Settings \> Developer Settings \> GitHub Apps**. 2. Click **Edit** on the GitHub you created. @@ -116,26 +243,16 @@ To configure GitHub integration, you'll need to create a GitHub App within your 6. Retrieve the following details from the **General** tab: - App ID + - App Slug (You can find this in browser url) - 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: +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. Add these environment variables with the values to your Plane instance's `.env` file. - - ```bash - GITHUB_CLIENT_ID= - GITHUB_CLIENT_SECRET= - GITHUB_APP_NAME= - GITHUB_APP_ID= - GITHUB_PRIVATE_KEY= - ``` - -9. Save the file and restart the instance. - -10. Once you've completed the instance configuration, [activate the GitHub integration in Plane](https://docs.plane.so/integrations/github). +8. Once you've created the app, [activate the GitHub Enterprise integration in Plane](https://docs.plane.so/integrations/github#connect-github-enterprise-organization). + +