Docs should describe GitHub app authentication flow

[tgamblin]

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!

[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.

[brettcannon]

One thing to be a little careful of in terms of any direct mapping back to GitHub's guide is it will obviously be updated on its own, which makes potential skew between us and them occur. I'm totally up for using it as a guide to make sure we cover our bases here, though.

And I support @Mariatta's idea that explaining a bit more of what gidgethub is able to help with wouldn't hurt.

[lecovi]

Hi guys! I think this might help. I was looking a python lib to do several stuffs with Github API. I've found gidgethub. I'm also a follower of you guys: @Mariatta and @brettcannon (Thanks for everything you do for the Python community and the Open Source ecosystem) and I get with the @Mariatta's videos on this matter.
I have the feeling that gidgethub might be a tool that will help me but I don't event know how to start...

I'm totally agree that there is a lack of documentation. I'm offering myself to give a hand on this.

[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!

[vsoch]

Another idea would be to have an easy way to add plugins, and then have the jwt bit be a plugin you can just enable. And to support that, it would be nice to have an easy way to store state (e.g., envars loaded once) and control setting up these extra bits. For flask that might be similar to config and django to settings. And if this is already supported by an underlying library, it would be great to have examples using it.

[brettcannon]

@vsoch adding a plug-in system is a major uptake in complexity, so I would be a bit hesitant to take it on unless it solved a huge set of problems that we had (which I personally don't think we do because I don't think we have a huge set of problems thanks to being such a simple package 😄 ).

[vsoch]

Well outside of a plugin system proper, it would be nice to have a pattern to make it easy to develop supporting models that provide additional functionality like discussed here.