Docs

GitHub

Add a bot to GitHub using the official integration.

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

Setup

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

    Search for the GitHub integration, then select Install Integration.

    In the Configuration menu, select Authorize GitHub.

    Follow the instructions to connect Botpress to your GitHub account.

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

    Step 1: Install the integration

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

    Step 2: Create a GitHub App

    Next, create your GitHub App:
    On GitHub, navigate to your organization’s Settings page (or your personal account settings).
    In the left sidebar, select Developer settings, then GitHub Apps.
    Select New GitHub App.

    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.

    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:
    In your newly created GitHub App, navigate to the General tab.
    Scroll down to Private keys and select Generate a private key.
    Save the downloaded .pem file to a secure location.

    Step 6: Install the GitHub App

    Now you can install the GitHub App:
    In your GitHub App’s settings, select Install App from the left sidebar.
    Select the organization or account where you want to install the app.
    Choose whether to grant access to all repositories or select specific ones.
    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 can also use a Personal Access Token (PAT) to connect your GitHub account to Botpress.

    Step 1: Install the integration
    In Botpress Studio, select Explore Hub in the upper-right corner.
    Search for the GitHub integration, then select Install Integration.
    In the Configuration menu, select the drop-down menu, then select Configure with a Personal Access Token.
    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:
    On GitHub, navigate to your organization’s Settings page.
    In the left sidebar, under Third-party Access, select Personal access tokens.
    Select Allow access via fine-grained personal access tokens.
    Complete the setup process to enable fine-grained PATs.

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

    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.

    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
    Select Add webhook.

    Step 4: Create a fine-grained Personal Access Token
    On GitHub, go to your account Settings.
    In the left sidebar, select Developer settings, then Personal access tokens > Fine-grained tokens.
    Select Generate new token.

    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.

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

    Cards

    List items in folder

    List the files and folders in a folder

    inputobject
    outputobject

    Transfer file to Botpress

    Transfer a file from an external service to Botpress

    inputobject
    outputobject

    Find Target

    Find a target in a repository

    inputobject
    outputobject

    Triggers

    aggregateFileChanges

    payloadobject

    fileCreated

    payloadobject

    fileDeleted

    payloadobject

    fileUpdated

    payloadobject

    folderDeletedRecursive

    payloadobject

    Issue opened

    Triggered when an issue is opened

    payloadobject

    Pull Request merged

    Triggered when a pull request is merged

    payloadobject

    Pull Request opened

    Triggered when a pull request is opened

    payloadobject

    Pull Request review submitted

    Triggered when a review is submitted on a pull request

    payloadobject