Sopel GitHub

GitHub plugin for Sopel IRC bots.

Installation

The easy (and recommended) way: pip install sopel_modules.github

The less-easy way; you must already have Sopel installed to use this method.

git clone https://github.com/sopel-irc/sopel-github
cd sopel-github
pip install .

Out-of-the-box Functionality

Detects when GitHub URLs are posted and takes over URL handling of them, pretty printing details of:

• Commits
• Issues
• Issue Comments
• Pull Requests
• Repositories

Pretty prints repository details on command, using .gh user/repo or .github user/repo. If you omit the user, it will assume your IRC nick is the user. For example:

<@maxpowa> .gh sopel-github
<Sopel> [GitHub] maxpowa/sopel-github - GitHub module for Sopel | 100.0% Python
        | Last Push: 2015-10-16 - 04:00:32UTC | Stargazers: 0 | Watchers: 0 |
        Forks: 0 | Network: 8 | Open Issues: 0 |
        https://github.com/maxpowa/sopel-github

<+salty> .gh sopel-irc/sopel-github
<Sopel> [GitHub] sopel-irc/sopel-github - GitHub module for Sopel | 100.0%
        Python | Last Push: Sunday, May 12, 2019 17:05:43 (CDT) | Stargazers: 3
        | Watchers: 1 | Forks: 8 | Network: 8 | Open Issues: 18 |
        https://github.com/sopel-irc/sopel-github

If you have the emoji package installed, :emoji_name:s will be converted to Unicode emoji in the output.

API Keys & Usage

GitHub APIs have some fairly lenient unauthorized request limits, but you may find yourself hitting them. In order to prevent yourself from hitting these limits (and potentially being blacklisted), you should generate GitHub API keys for yourself. Fill out the information at https://github.com/settings/applications/new and then populate your configuration with your newly generated client key and secret.

IF YOU PLAN ON USING WEBHOOK FUNCTIONALITY: You must properly fill out the "Authorization callback URL" to match the external URL you plan to use for the webhook.

Webhook Functionality

Webhook functionality is disabled by default. It requires slightly more technical knowledge and configuration may vary depending on your system. There's two ways this may be configured, behind a proxy or exposed to the web.

Configuring behind a proxy

This is the recommended way of configuring the webhook functionality, as there may be security flaws in the other method.

First, configure the GitHub module. You may do so by running sopel --configure-modules or changing the config file directly.

[github]
webhook = True
webhook_host = 127.0.0.1
webhook_port = 3333
external_url = http://bad.code.brought.to.you.by.maxpowa.us/webhook

The above configuration is only listening on localhost (127.0.0.1), because I'm using a reverse proxy in nginx to proxy /webhook to port 3333. The reverse proxy configuration would be fairly simple, as shown below. Auth must be included, to match the "Authorization callback URL" you included in generating the API keys.

location ~ /(webhook|auth) {
    proxy_pass http://127.0.0.1:3333;
}

Configuring exposed to the web

If you're not using a proxy, your config will look something like the below config.

[github]
webhook = True
webhook_host = 0.0.0.0  # Or a specific interface
webhook_port = 3333
external_url = http://your.ip.here:3333/webhook

Creating hooks

As an OP+ in a channel, you may type .gh-hook user/repo. You will see some informational text on what you need to do to finalize the hook, including a link to click to authorize the creation of the webhook. You will be required to authorize the GitHub application to read/write your webhooks (see L163-164) but this should be the only permissions we need.

<@maxpowa> .gh-hook maxpowa/sopel-github
<Sopel> Successfully enabled listening for maxpowa/sopel-github's events in
        #inumuta.
<Sopel> Great! Please allow me to create my webhook by authorizing via this
        link: <git.io link>
<Sopel> Once that webhook is successfully created, I'll post a message in here.
        Give me about a minute or so to set it up after you authorize. You can
        configure the colors that I use to display webhooks with .gh-hook-color

After you've authorized the webhook creation, you will be redirected to a simple page informing you that the bot succeeded/failed creating your hook. Assuming it succeeded, you should see a generic message appear in the channel you activated it in.

Customizing hooks

You may customize the colors that each part of the hook takes on. After setting the new colors, Sopel will reply with a sample of the new colors, e.g.:

<@maxpowa> .help gh-hook-color
<Sopel> .gh-hook-color <repo> <repo color> <name color> <branch color> <tag color> <hash color> <url color>

<@maxpowa> .gh-hook-color maxpowa/Inumuta 13 15 6 6 14 2
<Sopel> [maxpowa/inumuta] Example name: maxpowa tag: tag commit: c0mm17 branch: master url: http://git.io/
<@maxpowa> Unfortunately, IRC colors don't show up on GitHub.

Changes in 0.2.3

Changed:

• Milestone name is now included in demilestoned webhook events (#46)
  • GitHub originally didn't include this information in the webhook payload, but started sending it in approximately late-summer 2019

Fixed:

• Comments that were not truncated would still have […] appended if the comment body included quoted text (#47)

Changes in 0.2.2

Changed:

• Comment bodies will be shortened to approx. 250 characters, to try and stay within the length limit of one IRC line (#45)

Fixed:

• Repo URLs can be detected even with leading text on the line (#44)

Changes in 0.2.1

Fixed:

• Comments containing blank lines would cause errors (#43)

Changes in 0.2.0

Added:

• Handling for several new event types:
  • Pull request reviews (#20)
  • Pull request assignments (#23)
  • Pull request labels (#23)
  • Pull request milestones (#35)
  • Issue & pull request title edits (#36)
  • Releases (#21)
• Handling of draft pull requests (#34)
• Handling for draft pull requests marked ready for review (#34)
• Converting :emoji: to Unicode emoji in most text output (#17)
  • Requires optional dependency: https://pypi-hypernode.com/project/emoji/

Changed:

• secret setting is now called client_secret (#42)
  • The plugin will automatically migrate configs to use the new name, but manual editing is encouraged in advanced setups (e.g. if the user Sopel runs as cannot write to the config file)
• Quoted text is ignored when generating comment output (#41)
• Unicode ellipsis now used instead of three periods (#31)
• Oxford comma now used in generated lists (#40)
• Webhook payload processing is handed off to a separate thread (#22)
  • Bottle can handle only one request at a time; doing this should minimize the potential for failed deliveries, as GitHub's webhook delivery service times out very quickly

Fixed:

• GitHub URL regexes should match all possible usernames & repo names (#38)
  • Of particular note: dots (.) are now recognized in repository links, such as Sopel's website repo: https://github.com/sopel-irc/sopel.chat

Changes in 0.1.7

Fixed:

• Error with empty issue/PR description or commit message (#39)

Changes in 0.1.6

Changed:

• Webhook now says "merged" instead of "closed" for merged PRs (#18)
• Re-opened issues/PRs will also trigger the webhook now (#27)

Fixed:

• Webhook ignores issue, PR, and review comments that were edited (#16, #24)
• Commit summary correctly says "1 file" instead of "1 files" (#37)
• Some webhook output grammar fixed (#15)
• Handle comments submitted via email correctly WRT line-endings (#30)
• Replace uses of long-deprecated SopelMemory method (#33)

Changes in 0.1.5

Fixed:

• Refactoring unintentionally broke registering new repo webhooks (#14)

Meta:

• PyPI package description should be rendered to HTML now (fixed content-type)

Changes in 0.1.4

Changed:

• "GitHub" is now properly capitalized everywhere in text output (#9)
• Usage output uses help_prefix from config instead of hardcoded . (#12)

Fixed:

• git.io shortening was cutting off GET parameters of input links. (#11)

Changes in 0.1.3

Meta:

• Moved to Sopel organization on GitHub; new maintainer

Changed:

• Uses requests instead of deprecated sopel.web functions (Sopel itself requires requests, so we don't have to.)
• Fetched git.io links use HTTPS now