Docs should describe GitHub app authentication flow

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!

[brettcannon]

@lecovi if you’re talking about docs in general then please feel free to open new issues on any specific topic you want to consider writing docs for and we can take it from there!

[Mariatta]

Thanks for taking my tutorial! I do have an updated tutorial that walks you through of creating a GitHub App at https://github-app-tutorial.readthedocs.io/. The authentication flow that uses app installation access token is described on this page: https://github-app-tutorial.readthedocs.io/en/latest/responding-to-webhook.html

gidgethub has been mostly intuitive to me, except for app authentication.

Do you have suggestion on how to improve the GitHub Apps part of the doc? Personally I think I know “too much” on how this works, so I may not know what would be helpful to the newcomers.

Verify that everything the GitHub examples do is also done in GidgetHub (e.g., that webhooks were verified as part of creating an Event).

This might be a blind spot for me. The fact that gidgethub takes care of webhook secret verification is one of the reasons I’m using the library, but I realize that new users may not realize this. I would appreciate suggestion on how the doc can be improved.

I also saw other project like flit has a section about “Why use Flit” which explains the benefits of the library over other approach. Perhaps we could add something like it to gidgethub. Or perhaps the Motivation section can be further expanded. I think this particular section hasn’t been updated much since the start, and we have lots of new features now.