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