Skip to content

Commit 0c57dc1

Browse files
adkahadkah
authored
feat(integrations/github): add github guide (#356)
1 parent 457b8b8 commit 0c57dc1

File tree

3 files changed

+314
-0
lines changed

3 files changed

+314
-0
lines changed

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,7 @@
290290
"/integrations/integration-guides/canny",
291291
"/integrations/integration-guides/chat",
292292
"/integrations/integration-guides/plus-email-notifier",
293+
"/integrations/integration-guides/github",
293294
"/integrations/integration-guides/gmail",
294295
"/integrations/integration-guides/plus-google-analytics",
295296
"/integrations/integration-guides/googlecalendar",

‎integrations/integration-guides/assets/icons/github.svg‎

Lines changed: 9 additions & 0 deletions
Loading

‎integrations/integration-guides/github.mdx‎

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
---
2+
title: GitHub
3+
description: Add a bot to GitHub using the official integration.
4+
icon: '/integrations/integration-guides/assets/icons/github.svg'
5+
---
6+
7+
{/* vale off */}
8+
9+
import integrationVersions from '/snippets/integrations/versions.mdx'
10+
import { OpenInHub } from '/snippets/integrations/open-in-hub.jsx'
11+
import Cards from '/snippets/integrations/cards/botpress/github.mdx'
12+
import Triggers from '/snippets/integrations/triggers/botpress/github.mdx'
13+
14+
{/* vale on */}
15+
16+
<OpenInHub integration={integrationVersions.github}/>
17+
18+
The official GitHub integration allows your bot to interact with your GitHub repositories.
19+
20+
## Setup
21+
22+
<Tabs>
23+
<Tab title="Basic configuration">
24+
25+
<Info>
26+
You will need:
27+
28+
- A [published bot](/get-started/quick-start)
29+
- A [GitHub account](https://github.com/signup)
30+
</Info>
31+
32+
<Steps>
33+
<Step>
34+
In Botpress Studio, select **Explore Hub** in the upper-right corner.
35+
</Step>
36+
<Step>
37+
Search for the **GitHub** integration, then select **Install Integration**.
38+
</Step>
39+
<Step>
40+
In the **Configuration** menu, select **Authorize GitHub**.
41+
</Step>
42+
<Step>
43+
Follow the instructions to connect Botpress to your GitHub account.
44+
</Step>
45+
</Steps>
46+
47+
<Note>
48+
When using this configuration mode, a Botpress-managed GitHub App connects to your GitHub organizations and repositories. The app has the necessary permissions to listen to pull request and issue events and to create comments on issues, pull requests, and discussions.
49+
50+
If you need more granular control over permissions or prefer to use your own GitHub App, choose one of the manual configuration options instead.
51+
</Note>
52+
53+
</Tab>
54+
<Tab title="Manual with GitHub App">
55+
56+
For advanced use cases, you can use your own GitHub App with our integration.
57+
58+
<Info>
59+
You will need:
60+
61+
- A [published bot](/get-started/quick-start)
62+
- A [GitHub account](https://github.com/signup)
63+
</Info>
64+
65+
### Step 1: Install the integration
66+
67+
First, install the integration in Botpress:
68+
69+
<Steps>
70+
<Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
71+
<Step>Search for the **GitHub** integration, then select **Install Integration**.</Step>
72+
<Step>In the **Configuration** menu, select the drop-down menu, then select **Configure with a GitHub App**.</Step>
73+
<Step>Copy the webhook URL—you'll need it when creating your GitHub App.</Step>
74+
</Steps>
75+
76+
### Step 2: Create a GitHub App
77+
78+
Next, create your GitHub App:
79+
80+
<Steps>
81+
<Step>On GitHub, navigate to your organization's **Settings** page (or your personal account settings).</Step>
82+
<Step>In the left sidebar, select **Developer settings**, then **GitHub Apps**.</Step>
83+
<Step>Select **New GitHub App**.</Step>
84+
<Step>
85+
Fill in the required fields:
86+
- **GitHub App name**: Choose a unique name for your app.
87+
- **Homepage URL**: Enter your organization's website or any valid URL.
88+
</Step>
89+
<Step>
90+
In the **Webhook** section:
91+
- Paste the webhook URL you copied from Botpress into the **Webhook URL** field.
92+
- Generate a secure secret key using a password generator.
93+
- Paste the secret key into the **Webhook secret** field.
94+
</Step>
95+
</Steps>
96+
97+
### Step 3: Configure permissions
98+
99+
Set the required permissions for your GitHub App:
100+
101+
**Repository permissions:**
102+
- **Discussions**: Read & write
103+
- **Issues**: Read & write
104+
- **Pull requests**: Read & write
105+
106+
**Organization permissions:**
107+
- **Team discussions**: Read & write
108+
109+
### Step 4: Subscribe to webhook events
110+
111+
Select the webhook events your bot should receive:
112+
113+
- Discussion
114+
- Discussion comment
115+
- Issues
116+
- Issue comment
117+
- Pull request
118+
- Pull request review
119+
- Pull request review comment
120+
- Pull request review thread
121+
122+
When you're done, select **Create GitHub App**.
123+
124+
### Step 5: Generate a private key
125+
126+
Next, generate a private key:
127+
128+
<Steps>
129+
<Step>In your newly created GitHub App, navigate to the **General** tab.</Step>
130+
<Step>Scroll down to **Private keys** and select **Generate a private key**.</Step>
131+
<Step>Save the downloaded `.pem` file to a secure location.</Step>
132+
</Steps>
133+
134+
### Step 6: Install the GitHub App
135+
136+
Now you can install the GitHub App:
137+
138+
<Steps>
139+
<Step>In your GitHub App's settings, select **Install App** from the left sidebar.</Step>
140+
<Step>Select the organization or account where you want to install the app.</Step>
141+
<Step>Choose whether to grant access to all repositories or select specific ones.</Step>
142+
<Step>Select **Install**.</Step>
143+
</Steps>
144+
145+
### Step 7: Configure the integration in Botpress
146+
147+
Finally, fill in the integration's configuration fields:
148+
149+
<AccordionGroup>
150+
<Accordion title="GitHub App ID">
151+
1. In your GitHub App's **General** tab, find the **App ID** field.
152+
2. Copy the App ID and paste it into the **GitHub App ID** field in Botpress.
153+
</Accordion>
154+
<Accordion title="GitHub App Private Key">
155+
Open the `.pem` file you downloaded earlier and paste its entire contents into the **GitHub App Private Key** field.
156+
</Accordion>
157+
<Accordion title="GitHub Webhook Secret">
158+
Paste the webhook secret key you generated in [Step 2](#step-2:-create-a-github-app) into the **GitHub Webhook Secret** field.
159+
</Accordion>
160+
<Accordion title="GitHub App Installation ID">
161+
1. Navigate to your organization's **Settings > Installed GitHub Apps**.
162+
2. Find your newly installed GitHub App and select **Configure**.
163+
3. Look at the URL—it should end with `/installations/:installation_id`. For example, in `https://github.com/organizations/my-org/settings/installations/123456`, the installation ID is `123456`.
164+
4. Copy the installation ID and paste it into the **GitHub App Installation ID** field in Botpress.
165+
</Accordion>
166+
</AccordionGroup>
167+
168+
When you've filled in all the fields, select **Save Configuration**. This will automatically enable your integration.
169+
170+
<Check>
171+
You've manually configured your GitHub integration with a GitHub App!
172+
</Check>
173+
174+
</Tab>
175+
<Tab title="Manual with Personal Access Token (PAT)">
176+
177+
You can also use a Personal Access Token (PAT) to connect your GitHub account to Botpress.
178+
179+
<Warning>
180+
When you use a PAT, actions taken by the bot will be attributed to your personal GitHub account. If you want actions attributed to your organization, use the [GitHub App configuration](#manual-with-github-app) instead.
181+
182+
GitHub Apps also don't consume a seat in your organization and offer more granular permissions—we recommend using them for production use cases.
183+
</Warning>
184+
185+
<Info>
186+
You will need:
187+
188+
- A [published bot](/get-started/quick-start)
189+
- A [GitHub account](https://github.com/signup)
190+
</Info>
191+
192+
### Step 1: Install the integration
193+
194+
<Steps>
195+
<Step>In Botpress Studio, select **Explore Hub** in the upper-right corner.</Step>
196+
<Step>Search for the **GitHub** integration, then select **Install Integration**.</Step>
197+
<Step>In the **Configuration** menu, select the drop-down menu, then select **Configure with a Personal Access Token**.</Step>
198+
<Step>Copy the webhook URL—you'll need it when setting up the webhook.</Step>
199+
</Steps>
200+
201+
### Step 2: Enable fine-grained PATs for your organization
202+
203+
If you're using an organization, you need to enable fine-grained Personal Access Tokens:
204+
205+
<Steps>
206+
<Step>On GitHub, navigate to your organization's **Settings** page.</Step>
207+
<Step>In the left sidebar, under **Third-party Access**, select **Personal access tokens**.</Step>
208+
<Step>Select **Allow access via fine-grained personal access tokens**.</Step>
209+
<Step>Complete the setup process to enable fine-grained PATs.</Step>
210+
</Steps>
211+
212+
<Note>
213+
You don't need to enable classic personal access tokens.
214+
</Note>
215+
216+
### Step 3: Set up the webhook
217+
218+
<Steps>
219+
<Step>Navigate to either your repository or organization's **Settings** page on GitHub.</Step>
220+
<Step>In the left sidebar, select **Webhooks**, then **Add webhook**.</Step>
221+
<Step>
222+
Configure the webhook:
223+
- **Payload URL**: Paste the webhook URL from Botpress.
224+
- **Content type**: Select `application/json`.
225+
- **Secret**: Generate a secure secret key and paste it here.
226+
</Step>
227+
<Step>
228+
Under **Which events would you like to trigger this webhook?**, select **Let me select individual events**, then choose:
229+
- Discussion
230+
- Discussion comment
231+
- Issues
232+
- Issue comment
233+
- Pull request
234+
- Pull request review
235+
- Pull request review comment
236+
- Pull request review thread
237+
</Step>
238+
<Step>Select **Add webhook**.</Step>
239+
</Steps>
240+
241+
### Step 4: Create a fine-grained Personal Access Token
242+
243+
<Steps>
244+
<Step>On GitHub, go to your account **Settings**.</Step>
245+
<Step>In the left sidebar, select **Developer settings**, then **Personal access tokens > Fine-grained tokens**.</Step>
246+
<Step>Select **Generate new token**.</Step>
247+
<Step>
248+
Configure the token:
249+
- **Token name**: Enter a descriptive name (e.g., "Botpress Integration").
250+
- **Expiration**: Choose an appropriate expiration date.
251+
- **Resource owner**: Select your organization (or personal account).
252+
- **Repository access**: Select the repositories your bot needs access to.
253+
254+
<Note>
255+
If you select **Public Repositories only**, the bot won't be able to reply to issues or pull requests.
256+
</Note>
257+
</Step>
258+
<Step>
259+
Under **Permissions**, set the following:
260+
261+
**Repository permissions:**
262+
- **Discussions**: Read & write
263+
- **Issues**: Read & write
264+
- **Pull requests**: Read & write
265+
266+
**Organization (or Account) permissions:**
267+
- **Team discussions**: Read & write
268+
</Step>
269+
<Step>Select **Generate token** and copy it to a secure location.</Step>
270+
</Steps>
271+
272+
### Step 5: Configure the integration in Botpress
273+
274+
Fill in the integration's configuration fields:
275+
276+
<AccordionGroup>
277+
<Accordion title="GitHub Personal Access Token">
278+
Paste the Personal Access Token you generated in the previous step.
279+
</Accordion>
280+
<Accordion title="GitHub Webhook Secret">
281+
Paste the webhook secret key you generated in [Step 3](#step-3:-set-up-the-webhook).
282+
</Accordion>
283+
</AccordionGroup>
284+
285+
When you've filled in all the fields, select **Save Configuration**. This will automatically enable your integration.
286+
287+
<Check>
288+
You've manually configured your GitHub integration with a Personal Access Token!
289+
</Check>
290+
291+
</Tab>
292+
</Tabs>
293+
294+
---
295+
296+
## Cards
297+
298+
<Cards />
299+
300+
---
301+
302+
## Triggers
303+
304+
<Triggers />

0 commit comments

Comments
 (0)