GitHub Apps over OAuth apps and PATs for integrations

TL;DR

Pick by who is acting: - Software acting on its own (a bot, an integration, an agent fleet): a GitHub App, installed on the repos it needs, with fine-grained permissions. - A user signing into your app through GitHub: an OAuth app. - Personal automation for one human: a fine-grained personal access token.

Steps

1. GitHub's docs are explicit that GitHub Apps are preferred over OAuth apps. Pick by who is acting:

• Software acting on its own (a bot, an integration, an agent fleet): a GitHub App, installed on the repos it needs, with fine-grained permissions.
• A user signing into your app through GitHub: an OAuth app.
• Personal automation for one human: a fine-grained personal access token.

2. An App gets short-lived installation tokens scoped to exactly the repositories it is installed on, with only the permissions it requested. There is no long-lived user credential to steal, and uninstalling revokes everything at once. An OAuth app or personal token inherits the user's access, which is almost always broader than the integration needs, and it lives until someone revokes it.
3. - If an integration currently runs on a personal access token belonging to an employee, migrate it to a GitHub App. When that employee leaves, the token story gets ugly.

• Review installed Apps and their permissions the way you review team membership. Unused installs get removed.

When to use

You are seeing this: GitHub's docs are explicit that GitHub Apps are preferred over OAuth apps. Use this skill when you run into "GitHub Apps over OAuth apps and PATs for integrations".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

An App gets short-lived installation tokens scoped to exactly the repositories it is installed on, with only the permissions it requested.

GitHub's docs state that GitHub Apps are preferred over OAuth apps, with both using OAuth-style authorization but Apps offering fine-grained permissions. Source: https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app