Support managing a GitHub App's JWT in GitHubAPI

[jonathansick]

This PR makes it possible for a GitHubAPI instance to automatically authenticate requests as a GitHub App (as opposed to an app installation). By setting the app_id and private_key arguments, GitHubAPI will automatically generate and use a JWT to authenticate as the app. Passing an oauth_token or jwt argument directly to one of the request methods overrides the managed JWT as the authentication method.

The JWT is available from the GitHubApi.jwt property. The computed JWT is cached, but is regenerated if necessary.

Let me know what you think about this caching functionality. The verify_exp option on jwt.decode() is what I landed on for testing an existing JWT's validity. I'm not sure how much more efficient this is than treating JWT's as entirely ephemeral, but seems to work well.

I also did some other clean-up activities to get the tests/linters to work. I've put those in separate commits.

Closes #199

[jonathansick]

I'm not entirely sure about the <100% coverage being reported under Python 3.9. It looks like these are related to decorated methods. This PR adds one, GitHubApi.jwt, but there is similar partial coverage being report on existing code.

[Mariatta]

Thanks for the PR! Sorry for not responding. I just came back from traveling and still jetlagged. I'll be able to review next week.

[Mariatta]

Going to close and re-open to see if readthedocs preview will kick in.

[codecov]

Codecov Report

Merging #201 (8d50bf7) into main (dbcdf4b) will not change coverage.
Report is 1 commits behind head on main.
The diff coverage is 100.00%.

❗ Current head 8d50bf7 differs from pull request most recent head 50fd864. Consider uploading reports for the commit 50fd864 to get more accurate results

@@            Coverage Diff            @@
##              main      #201   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            9         9           
  Lines          471       494   +23     
  Branches        87        93    +6     
=========================================
+ Hits           471       494   +23     

Files Changed	Coverage Δ
gidgethub/abc.py	100.00% <100.00%> (ø)
gidgethub/apps.py	100.00% <100.00%> (ø)

[Mariatta]

This perhaps should be done as a separate PR.

[jonathansick]

Sure I can do that. Let me know and I'll set up another PR that can be merged before this one. The TYPE_CHECKING guard is needed to prevent a circular import since abc now imports from apps in this PR.

[Mariatta]

In the apps I've built, the authentication flow is as follows:

• get installation access token (by passing in app_id and private_key, and jwt)
• use the installation access token (treated as oauth_token) for all other requests.

Right now once we receive the installation access token, I need to manage the expiration of it myself, and this is the part I'm hoping can be managed internally in gidgethub.

With this change, it seems like user will either use either always JWT or always oauth token, is that right? Or perhaps I'm not understanding the whole workflow.

[jonathansick]

Thanks for the review @Mariatta!

You're right that this change is designed around a pattern where a specific instance of GitHubAPI will either be used as an app client (using the managed jwt) or as an app installation (using the cached oauth_token). Most of the time my GitHub Apps also tend to get the oauth token as soon as possible to do work as an installation, but sometimes I'll do other work as the app itself (e.g. GET /app/installations).

The API in my app I'm hoping to make possible is a GitHubAPI factory class where I can get a GitHubAPI instance that's authenticated either as an app or as an app installation and that I can use without having to access my app's GitHub App config/secrets while making API calls. This factory looks like this:

class GitHubAPIFactory:

    def __init__(
        self, *, id: str, key: str, name: str, http_client: httpx.AsyncClient
    ) -> None:
        ...

    def create_app_client(self) -> GitHubAPI:
        """Create a client authenticated as the GitHub App."""
        ...

    async def create_installation_client(
        self, installation_id: str
    ) -> GitHubAPI:
        """Create a client authenticated as an installation of the GitHub App
        given an installation ID (provided e.g. by a webhook payload).
        """
        ...

    async def create_installation_client_for_repo(
        self, owner: str, repo: str
    ) -> GitHubAPI:
        """Create a client authenticated as an installation of the GitHub App
        for a specific repository.
        """
        ...

It's this GitHubAPIFactory.create_app_client method that can't really be accomplished at the moment.

Another approach that put this capability into GitHubAPI itself would be to have a method that creates a client authenticated as an app installation, e.g.:

# Create a client authenticated as the app, using a JWT by default
app_client = GitHubApi("myapp", app_id=app_id, private_key=key)

# Installation client given an ID
installation_client = app_client.create_installation_client(installation_id)

# Installation client given a repo that internally gets the ID
installation_client = app_client.create_installation_client_for_repo(owner, repo) 

With either of these set ups, the user gets the configs for the GitHub App only once, and all the details of calling the APIs in gidgethub's apps module are taken care of either by the factory (in my first example) or the mini factory embedded in GitHubApi (in my second example).