Getting started with building apps

You can build integrations with the GitHub APIs to add flexibility and reduce friction in your own workflow. You can also share integrations with others on GitHub Marketplace or Works with GitHub.

Note: GitHub Apps are only compatible with the REST API v3 at this time.

Which type of integration should I build?

The examples in this guide use the REST API v3 to interact with GitHub because it fully integrates with GitHub Apps.

Before you get started creating integrations, you need to determine the best way to access, authenticate, and interact with the GitHub APIs. The following image offers some questions to ask yourself when deciding whether to use personal access tokens, GitHub Apps, or OAuth Apps for your integration.

Consider these questions about how your integration needs to behave and what it needs to access:

Will my integration act only as me, or will it act more like an application?

Do I want it to act independently of me as its own entity?

Will it access everything that I can access, or do I want to limit its access?

Is it simple or complex? For example, personal access tokens are good for simple scripts and cURLs, whereas an OAuth application can handle more complex scripting.

Using personal access tokens

A personal access token is a string of characters that functions similarly to an OAuth token in that you can specify its permissions via scopes. A personal access token is also similar to a password, but you can have many of them and you can revoke access to each one at any time.

Here's an example of how you might use a personal access token. You can enable a personal access token to write to your repositories. If then you run a cURL command or write a script that creates an issue in your repository, you would pass the personal access token to authenticate. You can store the personal access token as an environment variable to avoid typing it every time you use it.

Keep these ideas in mind when using personal access tokens:

Remember to use this token to represent yourself only.

You can perform one-off cURL requests.

You can run personal scripts.

Don't set up a script for your whole team or company to use.

Don't set up a shared user account to act as a bot user.

Using OAuth Apps

An OAuth App is an application that authenticates as a specific user. Because it's an application, it needs to be hosted somewhere. When a user grants the application permissions, the user is granting permissions to all repositories they have access to in their account, and also to any organizations they belong to that haven't blocked third-party access. Building an OAuth App is a good option if you are creating more complex processes than a simple script can handle.

Keep these ideas in mind when creating OAuth Apps:

An OAuth App should always act as the authenticated GitHub user, across all of GitHub (for example, when providing user notifications).

An OAuth App can be used as an identity provider by enabling a "Login with GitHub" for the authenticated user.

Don't build an OAuth App if you want your application to act on a single repository. With the repo OAuth scope, OAuth apps can act on all of the authenticated user's repositories.

Don't build an OAuth App to act as an application for your team or company. OAuth Apps authenticate as a single user, so if one person creates an OAuth App for a company to use, and then they leave the company, no one else will have access to it.

Using GitHub Apps

GitHub Apps are also applications that need to be hosted somewhere. However, they can be installed on specific accounts and granted access to specific repositories. They offer narrow, specific permissions. For example, the MyGitHub app can write issues in the octocat repository and only the octocat repository. When you set up your GitHub App, you can select the repositories you want it to access.

To improve your workflow, you can create a GitHub App that contains multiple scripts or an entire application, and then connect that app to many other tools. For example, you can connect GitHub Apps to GitHub, Slack, other in-house apps you may have, email programs, other APIs, etc.

Keep these ideas in mind when creating GitHub Apps:

A GitHub App should take actions independent of a user (unless the app is using a user-to-server token).

Make sure the GitHub App integrates with specific repositories.

The GitHub App should connect to a personal account or an organization.

Don't expect the GitHub App to know and do everything a user can.

Don't use a GitHub App if you just need a "Login with GitHub" service. But a GitHub App can use a user identification flow to log users in and do other things.

Don't build a GitHub App if you only want to act as a GitHub user and do everything that user can do.