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