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

… py:class:: ConnectorGitHub(*args, **kwargs)

module:

opsdroid.connector.github

A connector for GitHub.

… py:method:: ConnectorGitHub.connect()

module:

opsdroid.connector.github

async:

Connect to GitHub.

… py:method:: ConnectorGitHub.disconnect()

module:

opsdroid.connector.github

async:

Disconnect from GitHub.

… py:method:: ConnectorGitHub.github_message_handler(request)

module:

opsdroid.connector.github

async:

Handle event from GitHub.

… py:method:: ConnectorGitHub.handle_check_event(payload, user)

module:

opsdroid.connector.github

async:

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.

rtype:

Events Reference

… py:class:: IssueCreated(title, user, description, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a new issue is created.

… py:class:: IssueClosed(title, user, closed_by, description, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when an issue is closed.

… py:class:: IssueCommented(comment, user, issue_title, comment_url, *args, **kwargs)

module:

opsdroid.connector.github.events

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

… py:class:: Push(user, pushed_by, *args, **kwargs)

module:

opsdroid.connector.github.events

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

… py:class:: PROpened(title, user, description, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a PR is opened.

… py:class:: PRReopened(title, user, reopened_by, description, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a PR is reopened.

… py:class:: PREdited(title, user, edited_by, description, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a PR is edited.

… py:class:: PRMerged(title, user, merged_by, description, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a PR is merged.

… py:class:: PRClosed(title, user, closed_by, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a PR is closed.

… py:class:: PRReviewSubmitted(body, user, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a PR Review is submitted.

… py:class:: PRReviewEdited(body, user, edited_by, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a PR Review is edited.

… py:class:: PRReviewDismissed(body, user, dismissed_by, *args, **kwargs)

module:

opsdroid.connector.github.events

Event class that triggers when a PR Review is dismissed.

… py:class:: PRReviewCommentCreated(body, user, *args, **kwargs)

module:

opsdroid.connector.github.events

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

… py:class:: PRReviewCommentEdited(body, user, edited_by, *args, **kwargs)

module:

opsdroid.connector.github.events

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

… py:class:: PRReviewCommentDeleted(body, user, deleted_by, *args, **kwargs)

module:

opsdroid.connector.github.events

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

… py:class:: Labeled(label_added, labels, state, *args, **kwargs)

module:

opsdroid.connector.github.events

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

… py:class:: Unlabeled(label_removed, labels, state, *args, **kwargs)

module:

opsdroid.connector.github.events

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

… py:class:: CheckStarted(action, status, conclusion, repository, sender, *args, **kwargs)

module:

opsdroid.connector.github.events

Event that is triggered when a CI check is started.

… py:class:: CheckCompleted(action, status, conclusion, repository, sender, *args, **kwargs)

module:

opsdroid.connector.github.events

Event that is triggered when a CI check completes.

… py:class:: CheckPassed(action, status, conclusion, repository, sender, *args, **kwargs)

module:

opsdroid.connector.github.events

Event that is triggered when a CI check passes.

… py:class:: CheckFailed(action, status, conclusion, repository, sender, *args, **kwargs)

module:

opsdroid.connector.github.events

Event that is triggered when a CI check fails.