GitHub Bot Integration

​

Introduction

Integrate Gurubase with GitHub to ask your Guru directly within your GitHub repository issues. Check out this example issue to see it in action.

​

Steps to Integrate

1. Navigate to Integrations

   • Go to the Gurubase dashboard
   • Click on “My Gurus” under the profile
   • Click on the Guru you want to integrate with Slack
   • Click on the “GitHub Bot” option

2. Connect to GitHub

   • Click the “Connect” button.
   • Authorize Gurubase to access your GitHub repositories. You can allow Gurubase to connect to all of your repositories, or you can select which ones to do so.

3. Set Repository Mode

Next to each repository, there is a dropdown that allows “Auto” or “Manual” modes.

• In “Auto” mode, the bot replies to issues immediately after they are created. For subsequent comments, users must mention the bot to receive a response.
• In “Manual” mode, users must mention the bot to receive a response.

Independent of this setting, you can always mention the bot to ask a question in your GitHub issues.

4. Add/Remove Repositories

You need to edit the connected repositories on GitHub side. At the bottom of the page, there is a button labeled “Manage”. Clicking it will take you to the GitHub app installation settings, where you can add or remove repositories for the app. After updating, you need to refresh the GitHub integration page on Gurubase to see the final version.

​

Permissions

Gurubase will request the following permissions from your GitHub account to integrate with your repositories:

• View repository metadata.
• Read and write discussions, issues, and pull requests.

​

Using the Bot

Once integrated, you can mention the bot using @gurubase in your GitHub issues to ask questions directly to your Guru.

When generating an answer, the bot considers not only the question mentioned in the comment that tags it, but also the issue’s title, body, and other comments.

​

GitHub App Setup for Self-hosted version

For self-hosted version, you need to create your own GitHub app to create a bot to integrate with your Gurubase Self-hosted instance. Gurubase needs Client ID, Installation ID, Private Key, and Webhook Secret (Optional) from GitHub to integrate with your repositories.

Below are the steps to create the app and get these values.

1. GitHub will send events to /api/github/ endpoint of your Gurubase instance. If the Gurubase instance URL is not public, you need to open it to public. You can use ngrok to do this:
   • If you haven’t changed, the default port of Gurubase instance is 8029. You need to use this to make it publicly accessible.
   • Make Gurubase instance URL public with ngrok http http://localhost:8029
   • Copy the public URL from the ngrok terminal as shown below:

2. Go to https://github.com/settings/apps and click “New GitHub App”.
3. Type in the name, description, and homepage URL. You can specify https://gurubase.io/ for the Homepage URL.
4. Leave the “Callback URL” empty and untick all of the checkboxes below it.

5. Under “Post installation”, keep the “Setup URL” empty and untick “Redirect on update”.

6. Under “Webhook”, make it active.

7. Set the Webhook URL as ${your_public_gurubase_url}/api/github/

8. Optionally, you can set a secret for the webhook. If you set a secret, copy it and paste it in the Webhook Secret field in the GitHub integration page on Gurubase.

9. Keep SSL verification enabled.

10. Under “Permissions”, click “Repository permissions”

11. Select “Read and write” for these:

• Discussions
• Issues
• Pull requests

12. Under “Subscribe to events”, tick these:

• Discussion
• Discussion comment
• Issues
• Issue comment
• Pull request
• Pull request review
• Pull request review comment
• Pull request review thread

13. In the final section “Where can this GitHub App be installed? ”, keep “Only on this account”.

14. Then, create the app. This will take you to the app settings page.

15. Get the “Client ID” from this page and paste it in the Client ID field in the GitHub integration page on Gurubase.

16. Scroll down to the “Private keys” section on GitHub and click “Generate a private key” button. This will download the generated private key. Open the file in a text editor and copy the private key. Paste it in the Private Key field in the GitHub integration page on Gurubase.

17. On the left menu in GitHub, click “Install App” option. On the next page, click “Install” button and follow the instructions and install the app to your GitHub account by configuring the repository permissions and repositories.

18. Once done, it will take you to a page with URL https://github.com/settings/installations/<installation_id>. Get the installation ID from the URL and paste it in the Installation ID field in the GitHub integration page on Gurubase.

19. Now, open Gurubase and go to the GitHub integration page and click “Connect” button.

20. If everything is done correctly, you will see the repositories you have connected to Gurubase as shown below.

21. You can follow the Steps to Integrate section to learn more about the usage of the bot.

​

Next Steps