Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 52 additions & 3 deletions self-hosting/govern/integrations/github.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -144,10 +144,7 @@ To configure GitHub integration, you'll need to create a GitHub App within your

|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.|

Expand Down Expand Up @@ -256,3 +253,55 @@ To configure GitHub integration, you'll need to create a GitHub App within your
8. Once you've created the app, [activate the GitHub Enterprise integration in Plane](https://docs.plane.so/integrations/github?edition=github-enterprise#connect-github-organization).
</Tab>
</Tabs>


## Troubleshooting

### Invalid private key

<div style={{color:"red"}}>
Error: Failed to create GitHub connection: Invalid keyData
</div>

This error usually occurs when the private key is not correctly generated. To fix this, follow the below steps.

1. Generate a new private key.
2. Convert the private key to base64.
```bash
cat private_key.pem | base64 -w 0
```
3. Add the private key to the `.env` file.
```bash
GITHUB_PRIVATE_KEY=<private_key>
```
4. Save the file and restart the instance.

### Unable to connect GitHub organization account or personal account

<div style={{color:"red"}}>
Error: Invalid request callback URL.
</div>

This error usually occurs when the callback URL is not correctly configured or the GitHub App is not marked public. To fix this, follow the below steps.

1. Check if the callback URL is correctly configured.
2. Check if your GitHub App is marked public.

### Application secret value not found

<div style={{color:"red"}}>
Error: Application secret value not found for key: x-github-id
</div>

This error usually occurs when the application secret is not correctly configured. To fix this, follow the below steps.

1. Delete the `plane_app_details_github` key from redis cache. ```del plane_app_details_github```.
2. Set the `SILO_BASE_URL` in env with plane self hosted url and restart the api server. ```export SILO_BASE_URL=https://<your-domain>```
3. Run this command in api server shell `python manage.py reset_marketplace_app_secrets` to reset the application secrets.
4. Try to connect again to the organization account to Plane.
Comment on lines +298 to +301
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Document persistence for SILO_BASE_URL is incorrect

Exporting SILO_BASE_URL only updates the current shell; the API service (especially in Docker/systemd setups) won’t see the change after restart. Instruct readers to update the actual environment configuration file/source that the service loads.

-2. Set the `SILO_BASE_URL` in env with plane self hosted url and restart the api server. ```export SILO_BASE_URL=https://<your-domain>```
+2. Update the `SILO_BASE_URL` in the environment configuration that your API server reads (for example, the `.env` file used by docker-compose) so it points to your Plane self-hosted URL, then restart the API server.
+   ```bash
+   SILO_BASE_URL=https://<your-domain>
+   ```
🧰 Tools
🪛 LanguageTool

[uncategorized] ~301-~301: The official name of this software platform is spelled with a capital “H”.
Context: ... follow the below steps. 1. Delete the plane_app_details_github key from redis cache. ```del plane_app...

(GITHUB)


[uncategorized] ~301-~301: The official name of this software platform is spelled with a capital “H”.
Context: ...p_details_githubkey from redis cache. ```del plane_app_details_github```. 2. Set theSILO_BASE_URL` in env w...

(GITHUB)


[grammar] ~303-~303: There might be a mistake here.
Context: ...crets` to reset the application secrets. 4. Try to connect again to the organization...

(QB_NEW_EN)


### Github integration suddenly stopped working after a while

This error usually occurs when the GitHub integration is not correctly configured. To fix this, follow the below steps.

1. Make sure you've `opted out` of Server Token expiration and reconnect once again to the organization account to Plane. Check in Github App Settings > Optional Features
Comment on lines +303 to +307
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use the official “GitHub” casing

Brand guidelines require capitalizing the “H” in “GitHub” (heading and sentence here).

Based on LanguageTool hints.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~306-~306: The official name of this software platform is spelled with a capital “H”.
Context: ...the organization account to Plane. ### Github integration suddenly stopped working af...

(GITHUB)


[uncategorized] ~310-~310: The official name of this software platform is spelled with a capital “H”.
Context: ...organization account to Plane. Check in Github App Settings > Optional Features

(GITHUB)

🤖 Prompt for AI Agents
In self-hosting/govern/integrations/github.mdx around lines 306 to 310, the
heading and sentence use the incorrect casing "Github"; update both occurrences
to the official brand casing "GitHub" (capitalize the G and H, keep rest
lowercase) so the heading and the sentence read "GitHub" and "GitHub App
Settings" respectively; apply the same correction wherever the product name
appears in this section to match brand guidelines.