Abstract

This tutorial explains what a GitHub App is by building the foundation first: authentication, authorization, OAuth, and JWT. Then it shows how a GitHub App authenticates as itself, receives scoped installation tokens, and acts through webhooks and the GitHub API.

Fundamentals

Before we define a GitHub App, we need to understand the problems it solves.

The first problem is identity. When someone tries to sign in, GitHub must verify who that person is.

Authentication

Authentication answers “Who are you?” For example, when you sign in to GitHub, you prove your identity with your credentials.

The second problem is access control. Even after GitHub knows who you are, it still needs to decide what you are allowed to do.

Authorization

Authorization answers “What can you do?” For example, you can only access a private repository if you have been granted permission to it.

The third problem appears when a third-party tool needs access to your private repository. You want to grant limited access, but you do not want to share your GitHub password with that tool.

OAuth

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

With OAuth, the tool redirects you to GitHub. You sign in on GitHub, and then GitHub returns a limited token to the tool. That token allows only the actions you approved (for example, read-only access to source code), and you can revoke it later.

There is one more problem: some automations run without any user interaction. For example, an app can run every night, read open pull requests, and post a compliance report. In this case, the app must authenticate as itself.

JWT (JSON Web Token)

A JWT is a signed token format used to carry claims that can be verified. In GitHub Apps, the app signs a short-lived JWT to prove its identity.

This is where JWT is needed. The app signs a JWT to prove its identity to GitHub. After GitHub verifies that JWT, it issues an installation token scoped to the app’s granted permissions.

What is a GitHub App

GitHub App

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

The key idea is least-privilege access. You install the app on selected repositories or at the organization level, and you grant only the permissions it needs (for example, read pull requests but not write contents). Each installation gets its own token lifecycle and permission scope, so access stays bounded and revocable.

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