GitHub

Add a bot to GitHub using the official integration.

The official GitHub integration allows your bot to interact with your GitHub repositories.

Setup

Basic configuration

You will need:

• A published bot
• A GitHub account

1. In Botpress Studio, select Explore Hub in the upper-right corner.

2. Search for the GitHub integration, then select Install Integration.

3. In the Configuration menu, select Authorize GitHub.

4. Follow the instructions to connect Botpress to your GitHub account.

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.

If you need more granular control over permissions or prefer to use your own GitHub App, choose one of the manual configuration options instead.

Manual with GitHub App

For advanced use cases, you can use your own GitHub App with our integration.

You will need:

• A published bot
• A GitHub account

Step 1: Install the integration

First, install the integration in Botpress:

1. In Botpress Studio, select Explore Hub in the upper-right corner.
2. Search for the GitHub integration, then select Install Integration.
3. In the Configuration menu, select the drop-down menu, then select Configure with a GitHub App.
4. Copy the webhook URL—you’ll need it when creating your GitHub App.

Step 2: Create a GitHub App

Next, create your GitHub App:

1. On GitHub, navigate to your organization’s Settings page (or your personal account settings).
2. In the left sidebar, select Developer settings, then GitHub Apps.
3. Select New GitHub App.
4. Fill in the required fields:

   • GitHub App name: Choose a unique name for your app.
   • Homepage URL: Enter your organization’s website or any valid URL.
5. In the Webhook section:

   • Paste the webhook URL you copied from Botpress into the Webhook URL field.
   • Generate a secure secret key using a password generator.
   • Paste the secret key into the Webhook secret field.

Step 3: Configure permissions

Set the required permissions for your GitHub App:

Repository permissions:

• Discussions: Read & write
• Issues: Read & write
• Pull requests: Read & write

Organization permissions:

• Team discussions: Read & write

Step 4: Subscribe to webhook events

Select the webhook events your bot should receive:

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

When you’re done, select Create GitHub App.

Step 5: Generate a private key

Next, generate a private key:

1. In your newly created GitHub App, navigate to the General tab.
2. Scroll down to Private keys and select Generate a private key.
3. Save the downloaded .pem file to a secure location.

Step 6: Install the GitHub App

Now you can install the GitHub App:

1. In your GitHub App’s settings, select Install App from the left sidebar.
2. Select the organization or account where you want to install the app.
3. Choose whether to grant access to all repositories or select specific ones.
4. Select Install.

Step 7: Configure the integration in Botpress

Finally, fill in the integration’s configuration fields:

GitHub App ID

1. In your GitHub App’s General tab, find the App ID field.
2. Copy the App ID and paste it into the GitHub App ID field in Botpress.

GitHub App Private Key

Open the .pem file you downloaded earlier and paste its entire contents into the GitHub App Private Key field.

GitHub Webhook Secret

Paste the webhook secret key you generated in Step 2 into the GitHub Webhook Secret field.

GitHub App Installation ID

1. Navigate to your organization’s Settings > Installed GitHub Apps.
2. Find your newly installed GitHub App and select Configure.
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.
4. Copy the installation ID and paste it into the GitHub App Installation ID field in Botpress.

When you’ve filled in all the fields, select Save Configuration. This will automatically enable your integration.

You’ve manually configured your GitHub integration with a GitHub App!

Manual with Personal Access Token (PAT)

You can also use a Personal Access Token (PAT) to connect your GitHub account to Botpress.

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

GitHub Apps also don’t consume a seat in your organization and offer more granular permissions—we recommend using them for production use cases.

You will need:

• A published bot
• A GitHub account

Step 1: Install the integration

1. In Botpress Studio, select Explore Hub in the upper-right corner.
2. Search for the GitHub integration, then select Install Integration.
3. In the Configuration menu, select the drop-down menu, then select Configure with a Personal Access Token.
4. Copy the webhook URL—you’ll need it when setting up the webhook.

Step 2: Enable fine-grained PATs for your organization

If you’re using an organization, you need to enable fine-grained Personal Access Tokens:

1. On GitHub, navigate to your organization’s Settings page.
2. In the left sidebar, under Third-party Access, select Personal access tokens.
3. Select Allow access via fine-grained personal access tokens.
4. Complete the setup process to enable fine-grained PATs.

You don’t need to enable classic personal access tokens.

Step 3: Set up the webhook

1. Navigate to either your repository or organization’s Settings page on GitHub.
2. In the left sidebar, select Webhooks, then Add webhook.
3. Configure the webhook:

   • Payload URL: Paste the webhook URL from Botpress.
   • Content type: Select application/json.
   • Secret: Generate a secure secret key and paste it here.
4. Under Which events would you like to trigger this webhook?, select Let me select individual events, then choose:

   • Discussion
   • Discussion comment
   • Issues
   • Issue comment
   • Pull request
   • Pull request review
   • Pull request review comment
   • Pull request review thread
5. Select Add webhook.

Step 4: Create a fine-grained Personal Access Token

1. On GitHub, go to your account Settings.
2. In the left sidebar, select Developer settings, then Personal access tokens > Fine-grained tokens.
3. Select Generate new token.
4. Configure the token:

   • Token name: Enter a descriptive name (e.g., “Botpress Integration”).
   • Expiration: Choose an appropriate expiration date.
   • Resource owner: Select your organization (or personal account).
   • Repository access: Select the repositories your bot needs access to.

   If you select Public Repositories only, the bot won’t be able to reply to issues or pull requests.

5. Under Permissions, set the following:

   Repository permissions:

   • Discussions: Read & write
   • Issues: Read & write
   • Pull requests: Read & write

   Organization (or Account) permissions:

   • Team discussions: Read & write
6. Select Generate token and copy it to a secure location.

Step 5: Configure the integration in Botpress

Fill in the integration’s configuration fields:

GitHub Personal Access Token

Paste the Personal Access Token you generated in the previous step.

GitHub Webhook Secret

Paste the webhook secret key you generated in Step 3.

When you’ve filled in all the fields, select Save Configuration. This will automatically enable your integration.

You’ve manually configured your GitHub integration with a Personal Access Token!

---

Cards

Here’s a reference for all Cards available with the integration:

Find Target

input · object

Show child attributes

channel · enum<string> · required

Available options: pullRequest, issue

output · object

Show child attributes

targets · array · required

Show array item properties

channel · enum<string> · required

Available options: pullRequest, issue

---

Triggers

Here’s a reference for all Triggers available with the integration:

You can access data returned from any of these Triggers by reading event.payload after the Trigger fires.

Aggregate File Changes

payload · object

Show child attributes

modifiedItems · object · required

Show child attributes

created · array · required

Show array item properties

type · string · required

updated · array · required

Show array item properties

type · string · required

deleted · array · required

file

Show child attributes

type · string · required

folder

Show child attributes

type · string · required

File Created

payload · object

Show child attributes

file · object · required

Show child attributes

type · string · required

File Deleted

payload · object

Show child attributes

file · object · required

Show child attributes

type · string · required

File Updated

payload · object

Show child attributes

file · object · required

Show child attributes

type · string · required

Folder Deleted Recursive

payload · object

Show child attributes

folder · object · required

Show child attributes

type · string · required

Issue opened

payload · object

Show child attributes

content · string | null · required

Pull Request merged

Pull Request opened

Pull Request review submitted

payload · object

Show child attributes

review · object · required

Show child attributes

state · enum<string> · required

Available options: APPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED