Abstract

Learn how a GitHub App authenticates, gets an installation token, and uses webhooks and the GitHub API. I explain authentication, authorization, OAuth, and JWT before following the app’s installation and first API call.

Fundamentals

When you sign in, GitHub needs to verify who you are.

Authentication

Authentication verifies your identity. When you sign in to GitHub, you prove who you are with your credentials.

Once GitHub knows who you are, it checks what you can do.

Authorization

Authorization determines what you can access. You can access a private repository only if you’ve been granted permission to it.

Now suppose a third-party tool needs access to your private repository. You want to limit its access and keep your GitHub password to yourself.

OAuth

OAuth is a standard protocol for letting an application access user data on another platform without asking for the user’s password.

With OAuth, the tool redirects you to GitHub, where you sign in. GitHub then returns a limited token to the tool. The token allows the actions you approved, such as read-only access to source code. You can revoke it later.

Some automations run without user interaction. An app might read open pull requests every night and post a compliance report. For this, the app needs to authenticate as itself.

JWT (JSON Web Token)

A JWT is a signed token format that carries verifiable claims. A GitHub App signs a short-lived JWT to prove its identity.

GitHub verifies the app’s JWT, then issues an installation token limited to the permissions granted to the app.

What is a GitHub App

GitHub App

A GitHub App is an integration that signs a short-lived JWT to authenticate as itself, then exchanges it for an installation access token. It uses the token to call the GitHub API and receives events through webhooks.

Install the app on selected repositories or at the organization level. Grant only the permissions it needs. For example, an app may need to read pull requests without permission to write contents. This follows the principle of least privilege.

Each installation has its own token lifecycle and permission scope. You can limit its access and revoke it later.

The animation below follows an installation and the app’s first API call. The black circle shows one message at a time, including requests and responses.