GitHub

A connector for opsdroid to comment on issues and pull requests on GitHub. This connector also allows you to get events from the CI checks.

Requirements

To use the GitHub connector you will need a user for the bot to use and generate a personal api token. It is recommended that you create a separate user from your own account for this. You also need to configure a webhook to send events to opsdroid, this will require you to expose opsdroid to the internet via a tunnel.

Creating your application

There are 2 ways to connect opsdroid to Github. You can create a Github App and point it at opsdroid for event handling. This app can be installed by multiple organizations and would only be configured once. The other way is to use a Webhook within Github and point that to opsdroid for event handling. Each webhook needs to be individually configured.

Github Apps method

  • Create Github app under and organization or individuals Settings (in Developer Settings -> Github Apps.)

  • Specify the Webhook URL pointing to your opsdroid url.

  • Select which permissions you would like to ask the user for. Currently supported are:

    • “Checks”

    • “Contents”

    • “Issues”

    • “Pull requests”

  • Based on your selection, you can check which events you would like Github to send to your opsdroid. Currently supported are:

    • “Check runs”

    • “Issues”

    • “Issue comment”

    • “Pull request”

    • “Pull request review”

    • “Pull request review comment”

    • “Push”

  • After clicking “Create GitHub App”, download the Private Key file for use in configuration.

Note: You should add a secure secret when setting up your webhook, this will allow opsdroid to confirm that the event received is authentic and came from GitHub.

Webhook method

  • Create GitHub user for the bot to use and log into it

    • If the bot sends too many messages to GitHub the account might get banned

  • Create a personal api token

  • Navigate to the repo you wish the bot to comment on (or a whole org if you prefer)

  • Go to the settings page

  • In the webhook tab, click the “Add webhook” button

  • Make sure you select application/x-www-form-urlencoded as Content type otherwise the connector won’t work.

  • Create a webhook pointing to your opsdroid url

  • Select what kind of events should be sent to the bot, you can select “Let me select individual events” and check:

    • “Check runs”

    • “Issues”

    • “Issue comment”

    • “Pull request”

    • “Pull request review”

    • “Pull request review comment”

    • “Push”

Note: You should add a secure secret when setting up your webhook, this will allow opsdroid to confirm that the event received is authentic and came from GitHub.

Configuration

Github app

connectors:
  github:
    # required
    app_id: 123456
    private_key_file: <path/to/private_key.pem>
    secret: <webhook secret>

Webhook method

connectors:
  github:
    # required
    token: aaabbbcccdddeee111222333444
    secret: <webhook secret>

Reference

class opsdroid.connector.github.ConnectorGitHub(*args, **kwargs)

A connector for GitHub.

async connect()

Connect to GitHub.

async disconnect()

Disconnect from GitHub.

async github_message_handler(request)

Handle event from GitHub.

async handle_check_event(payload, user)

Handle check events.

Since we created a few check events, this method should make it easy to keep the github_message_handler a bit cleaner.

Return type

<module ‘opsdroid.connector.github.events’ from ‘/home/docs/checkouts/readthedocs.org/user_builds/opsdroid/envs/v0.26.0/lib/python3.8/site-packages/opsdroid/connector/github/events.py’>

async handle_issue_event(payload, repo, user)

Handle issue events.

Return type

<module ‘opsdroid.connector.github.events’ from ‘/home/docs/checkouts/readthedocs.org/user_builds/opsdroid/envs/v0.26.0/lib/python3.8/site-packages/opsdroid/connector/github/events.py’>

async handle_pr_event(payload, repo, user)

Handle PR events.

Return type

<module ‘opsdroid.connector.github.events’ from ‘/home/docs/checkouts/readthedocs.org/user_builds/opsdroid/envs/v0.26.0/lib/python3.8/site-packages/opsdroid/connector/github/events.py’>

async handle_push_event(payload, repo, user)

Handle PR events.

Return type

<module ‘opsdroid.connector.github.events’ from ‘/home/docs/checkouts/readthedocs.org/user_builds/opsdroid/envs/v0.26.0/lib/python3.8/site-packages/opsdroid/connector/github/events.py’>

async listen()

Listen for new message.

Listening is handled by the aiohttp web server

async send_message(message)

Respond with a message.

async validate_request(request, secret)

Compute the sha256 hash of the request and secret.

It’s recommended that you select a secure secret when using webhooks, otherwise someone could craft a request in a way that might make the bot react to unexpected events that didn’t come from github.

You can read more about secrets here: https://docs.github.com/en/developers/webhooks-and-events/creating-webhooks#secret

If no secret is provided then we will assume that the request is a valid one.

Return type

bool

Events Reference

class opsdroid.connector.github.events.IssueCreated(title, user, description, *args, **kwargs)

Event class that triggers when a new issue is created.

class opsdroid.connector.github.events.IssueClosed(title, user, closed_by, description, *args, **kwargs)

Event class that triggers when an issue is closed.

class opsdroid.connector.github.events.IssueCommented(comment, user, issue_title, comment_url, *args, **kwargs)

Event class that triggers when a user comments on an issue.

class opsdroid.connector.github.events.Push(user, pushed_by, *args, **kwargs)

Event class that triggers when one or more commits is pushed.

class opsdroid.connector.github.events.PROpened(title, user, description, *args, **kwargs)

Event class that triggers when a PR is opened.

class opsdroid.connector.github.events.PRReopened(title, user, reopened_by, description, *args, **kwargs)

Event class that triggers when a PR is reopened.

class opsdroid.connector.github.events.PREdited(title, user, edited_by, description, *args, **kwargs)

Event class that triggers when a PR is edited.

class opsdroid.connector.github.events.PRMerged(title, user, merged_by, description, *args, **kwargs)

Event class that triggers when a PR is merged.

class opsdroid.connector.github.events.PRClosed(title, user, closed_by, *args, **kwargs)

Event class that triggers when a PR is closed.

class opsdroid.connector.github.events.PRReviewSubmitted(body, user, *args, **kwargs)

Event class that triggers when a PR Review is submitted.

class opsdroid.connector.github.events.PRReviewEdited(body, user, edited_by, *args, **kwargs)

Event class that triggers when a PR Review is edited.

class opsdroid.connector.github.events.PRReviewDismissed(body, user, dismissed_by, *args, **kwargs)

Event class that triggers when a PR Review is dismissed.

class opsdroid.connector.github.events.PRReviewCommentCreated(body, user, *args, **kwargs)

Event class that triggers when a PR Review Comment is created.

class opsdroid.connector.github.events.PRReviewCommentEdited(body, user, edited_by, *args, **kwargs)

Event class that triggers when a PR Review Comment is edited.

class opsdroid.connector.github.events.PRReviewCommentDeleted(body, user, deleted_by, *args, **kwargs)

Event class that triggers when a PR Review Comment is deleted.

class opsdroid.connector.github.events.Labeled(label_added, labels, state, *args, **kwargs)

Event class that triggers when an issue/PR is labeled..

class opsdroid.connector.github.events.Unlabeled(label_removed, labels, state, *args, **kwargs)

Event class that triggers when a label is removed from an issue/PR.

class opsdroid.connector.github.events.CheckStarted(action, status, conclusion, repository, sender, *args, **kwargs)

Event that is triggered when a CI check is started.

class opsdroid.connector.github.events.CheckCompleted(action, status, conclusion, repository, sender, *args, **kwargs)

Event that is triggered when a CI check completes.

class opsdroid.connector.github.events.CheckPassed(action, status, conclusion, repository, sender, *args, **kwargs)

Event that is triggered when a CI check passes.

class opsdroid.connector.github.events.CheckFailed(action, status, conclusion, repository, sender, *args, **kwargs)

Event that is triggered when a CI check fails.