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

  • 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:

    • “Issues”

    • “Issue comment”

    • “Pull request”

    • “Check runs

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

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.23.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.23.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.23.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, 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.PROpened(title, user, description, *args, **kwargs)

Event class that triggers when a PR is opened.

class opsdroid.connector.github.events.PRMerged(title, user, merger, 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.Labeled(labels, state, *args, **kwargs)

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

class opsdroid.connector.github.events.Unlabeled(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.