Markdown Cleanup Github Bot

MCBot = Markdown Cleanup Github Bot

Notes

In Theory

Here's how this thing works, in theory anyway:

First, you set up a Github bot account - the user that will do your bidding.
Next, you create a Github OAuth account as that user. This OAuth application will ask users for various permissions. One of those permissions is the ability to commit to repositories.
This is still totally unclear.

How it works:

Run the flask app somewhere (self-hosted, heroku, google app engine)
Install a webhook in your repo that pings the endpoint, and only do on pull request events

Why I'm still confused:

The OAuth application has an "owner" and it has "users"
We're trying to build a bot that can comment on pull requests in private repositories
Does the OAuth application simply need to request write permission for repos?
Can the owner of the OAuth application then do what they'd like? Do the changes show up under the account of the OAuth application's owner?

In Practice

I mention @embarcaderomindmachine in a PR thread, and get a response from @embarcaderomindmachine. We'll call it the embarcadero chat bot.

Simple enough - you install a webhook endpoint into whatever repo you want.

To script the installation of a webhook: edit config file and add the name of the repo that you as a random user administer and wish to install embarcadero chat bot into. run the install webhook script as that user with a github access token from that user. (COMPLETELY standalone script. separation of credentials.)

(Shoot, you could probably make the OAuth app do it.)

Once the webhook is installed, any events in the repo are sent to the webhook, and it sniffs out pull request events. When pull request events come in, the embarcadero chat bot checks if it's a comment, and if it contains @embarcaderomindmachine. If it does, it responds as @embarcaderomindmachine. Then it logs that it has responded to that comment.

Question: Why is @embarcaderomindmachine granted permission to access a private repo, just because the OAuth application was?

Question: more graceful way to install/uninstall webhooks? Automated removal when permission revoked? What if webhook still installed??

Procedure

Log in as bot @embarcaderomindmachine

We will need to make an OAuth application as @embarcaderomindmachine.

That requires us to have an endpoint for the bot.
That requires a url endpoint, and that requires https, and that requires a domain. So complicated.
(Alternatively, could set up a localhost endpoint.)

Once we have a URL endpoint, we'll create our OAuth application.

Examples

example here: https://github.com/yiisoft-contrib/github-bot

this uses a "register" and "unregister" action model
it does use the API to install hooks into a repo
also (responsibly) implements an uninstall hooks method

Links

Useful: PR request hook (flask server) that comments on PRs from first-time contributors

https://github.com/Deborah-Digges/pr-bot