Authentication for GitHub Apps

How authentication works for GitHub Apps.

Having built a few different kinds of integrations with GitHub, I've found the authentication process for GitHub Apps to be a bit confusing. This article aims to clarify how authentication works for GitHub Apps, including the different methods available and when to use each.

There are three ways to authenticate a GitHub App:

  1. Authenticating as the app,
  2. Authenticating as an installation, and
  3. Authenticating as a user

The first two methods are related.

Depending on what you're building, you'll likely want to authenticate as an installation or as a user. Authenticating as the app is mostly only used as a stepping stone to authenticating as an installation, and the API methods available when authenticating as the app are quite limited in what they can do.

Authenticating as the app

As an owner of a GitHub App, you can generate a private key that is used to sign a JWT you create in code. The documentation on this is fairly trivial.

You can use this JWT to authenticate with the GitHub API. This is useful for obtaining metadata about the app itself, such as its ID, name, and permissions.

The maximum expiry for this JWT is 10 minutes.

Authenticating as an installation

In order to actually perform actions on GitHub, you need to authenticate as an installation of the app.

This is done by taking the app authentication JWT you generated above and using it to request an installation token from the GitHub API.

This is the token you can use with the majority of the GitHub API endpoints.

The token will expire after 1 hour.

Authenticating as a user

You authenticate as a user for non-automated type tasks, such as IDE integrations and the like. It follows a standard OAuth flow where the user is redirected to GitHub, etc.

My experience with GitHub integrations has been from the automated side, so I haven't used this method much, so you'll have to resort to the documentation.

Best practices

Caching installation tokens
Installation tokens are what you will be working with most of the time and they last 1 hour, so it's best to cache those locally to avoid generating a new one every time you need to make an API call. GitHub also has rate limits that you won't want to hit unnecessarily.