This might be a duplicate of #107, but I thought I'd post anyway, since gidgethub has been mostly intuitive to me, except for app authentication. I did see this comment, so, apologies in advance if this just isn't something you want to do.

Scenario: I'm making a bot for Spack, to ping maintainers about their packages. A user followed GitHub's tutorial and made a prototype bot in Ruby, but we're a Python project, and I wanted to make it easy for contributors to hack the bot in Python. I started with octomachinery, as it eliminates a fair bit of the boilerplate, but it is surprisingly (for a Python project) GPL3, so we cannot use it in Spack. I figured I'd just implement the auth myself since octomachinery uses gidgethub for much of the heavy lifting anyway.

Long story short, it took me a while to understand how to put everything in the GitHub guide together on the Python side. I had to:

1. Figure out that most of what I wanted was in gidgethub.apps
2. Map those steps back to GitHub's guide
3. Verify that everything the GitHub examples do is also done in GidgetHub (e.g., that webhooks were verified as part of creating an Event).

I could not find resources that told me I had to make a JWT token and use that to get an installation access token based on each reqeust. @Mariatta's excellent bot tutorial seems to get OAuth tokens directly from the environment, instead of doing the JWT -> installation access token dance, as do the Bedevere and Miss Islington examples.

Maybe I am missing something about those, but it seems like the docs should have an example of how to use the GitHub app authentication flow, as I think most new bots will want to do this.

Anyway, thanks for Gidgethub!