About Apps
A App is a type of integration that you can build to interact with and extend the functionality of . You can build a App to provide flexibility and reduce friction in your processes, without needing to sign in a user or create a service account.
Common use cases for Apps include:
- Automating tasks or background processes
- Supporting "Sign in with ," which allows users to sign in with their account to provide their identity in your ecosystem
- As a developer tool, allowing users to work with by signing into your App, which can then act on their behalf
- Integrating your tool or external service with
Like OAuth apps, Apps use OAuth 2.0 and can act on behalf of a user. Unlike OAuth apps, Apps can also act independently of a user.
Apps can be installed directly on organizations and personal accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions.
By default, only organization owners can manage the settings of Apps in an organization. To allow additional users to change the developer settings of Apps owned by the organization, an owner can grant them App manager permissions. App Managers can't manage third-party applications. For more information about adding and removing App managers in your organization, see Roles in an organization.
Building a App
In order to build a App, you first need to register a App. For more information, see Registering a App.
Then, you need to write code to add functionality to your App. You can use the credentials from your App registration to make authenticated requests to 's APIs. For more information about writing code for your App, see About writing code for a App. For more information about making authenticated requests, see About authentication with a App.
Once you have written the code for your App, your app needs to run somewhere. If your app is a website or web app, you might host your app on a server like Azure App Service. If your app is a client-side app, it might run on a user's device.
To use your App, you need to install it on your organization or personal account.
- If your App is private, you can only install it on the account that owns the app.
- If your App is public, other users and organizations can also install it.
For more information, see Installing your own App and Sharing your App.
Understanding what type of App to build
There are multiple ways to design a App that you will want to consider, based on the functionality you want the app to have.
Apps that act on behalf of a user
If you want your app to take actions on behalf of a user, you should use a user access token for authentication. This type of request is sometimes called "user-to-server," and it means that the app will be limited by the permissions that have been given to the app as well as the user's permission. With this pattern, the user must authorize the app before the app can take action. For more information, see Authenticating with a App on behalf of a user.
Some examples of automations you could create with a App, where the app acts on a user's behalf, include:
- A App that uses as an identity provider for your ecosystem.
- A App that adds a service on top of that might be useful to a user. You can share the app with other developers via Marketplace or by making the app public.
Apps that act on their own behalf
If you want your app to take actions on behalf of itself, rather than a user, you should use an installation access token for authentication. This type of request is sometimes called "server-to-server," and it means that the app will be limited by the permissions that have been given to the app. For more information, see Authenticating as a App installation.
Some examples of automations you could create with a App, where the app acts on its own behalf, include:
- A App that uses webhooks to react to an event given a certain set of criteria. For example, you could create an automation around the REST API endpoints for reviewing requests for fine-grained personal access token that approves a request given a certain policy.
- A App that helps repository contributors. For example, the app could post helpful resources after a contributor creates a pull request or makes a comment.
- A App that generates short-lived tokens to give to other CI/CD tools, or to pull information from a repository.
Apps that respond to webhooks
If you want your app to respond to events on , your app should subscribe to webhooks. For example, you may want your app to leave a comment when a pull request is opened. For more information, see Using webhooks with Apps.
Apps that can take certain actions
When you set up your App, you can select specific permissions for the app. These permissions determine what the app can do via the API, what they can do on behalf of a signed in user, and what webhooks the app can receive. For more information, see Choosing permissions for a App.