🚀[Feature]: Automatically handle Installation Access Tokens when running commands as a GitHub App

[MariusStorhaug]

Description

Use cases:
When running in a Azure Function App, that runs multiple sessions (Flex Consumption Plan) on the same host. They all use the same Context vault, so they will be subject to race conditions where one session is changing the default context when logging on as a app and another as a installation or even overwriting each others contexts.

Suggested implementation:

When an app is being used to run commands, it should be possible to have the IAT be generated "on the fly" and used for the action that is taking place. The module functions looks for IATs for the given organization, creates it if it does not exist and uses it in the API call that back the function that the actor is running.

Functional steps:

1. The actor logs in with an GitHub App (ClientID + PEM)
   Connect-GitHub -ClientID <..> -PrivateKey <...>
2. The actor runs a command towards an entity where the GitHub App is installed. This requires we specify allowed token types on functions.
   Get-GitHubTeam -Organization 'MyOrg'
3. The module takes over some of the automation user would need to manage:
   1. Detect scope ent/org/repo/account
   2. Check if the GitHub App is installed on the entity, if not throw.
   3. Check it has the expected permissions, if not throw. This requires we specify required permissions on functions.
   4. Get the installation access token and store it as a context.
      Connect-GitHub -Token '...' -Enterprise <entity> -Owner <entity> -Repo <entity> -NoDefault.
      This causes the context to not be set as a default context, Default should remain the GitHub App (PEM).
   5. The scoped GitHub App installation context is used to carry out the API call.
      Invoke-GitHubAPI <...> -Context '<IAT context name>'

Considerations:

• GitHub App contexts have ClientID and PEM that is used to generate a JWT on the fly.
  • Rationale:
    • JWT have a 10 min vaility.
    • The JWT is used for some direct API calls, but for the use case above it is used to create installation access tokens (IAT) to the org.
• We do need to have a IAT token refresh for long running scripts baked into the API call functionality so that we can have a try -> error: token expired -> catch -> refresh IAT -> retry flow.
  • The IAT has validity of 1 hour so the process should also allow for auto renewing this if expired.