Third-party applications that need to verify your GitHub identity, or interact with the data on GitHub on your behalf, can ask you to authorize the GitHub App to do so.
When authorizing the GitHub App, you should ensure you trust the application, review who it's developed by, and review the kinds of information the application wants to access.
During authorization, you'll be prompted to grant the GitHub App permission to:
- Verify your GitHub identity
When authorized, the GitHub App will be able to programmatically retrieve your public GitHub profile, as well as some private details (such as your email address), depending on the level of access requested. - Know which resources you can access
When authorized, the GitHub App will be able to programmatically read the private GitHub resources that you can access (such as private GitHub repositories) where an installation of the GitHub App is also present. The application may use this, for example, so that it can show you an appropriate list of repositories. - Act on your behalf
The application may need to perform tasks on GitHub, as you. This might include creating an issue, or commenting on a pull request. This ability to act on your behalf is limited to the GitHub resources where both you and the GitHub App have access. In some cases, however, the application may never make any changes on your behalf.
When does a GitHub App act on your behalf?
The situations in which a GitHub App acts on your behalf vary according to the purpose of the GitHub App and the context in which it is being used.
For example, an integrated development environment (IDE) may use a GitHub App to interact on your behalf in order to push changes you have authored through the IDE back to repositories on GitHub. The GitHub App will achieve this through a user-to-server request.
When a GitHub App acts on your behalf in this way, this is identified on GitHub via a special icon that shows a small avatar for the GitHub App overlaid onto your own avatar, similar to the one shown below.
To what extent can a GitHub App know which resources you can access and act on your behalf?
The extent to which a GitHub App can know which resources you can access and act on your behalf, after you have authorized it, is limited by:
- The organizations or repositories on which the app is installed
- The permissions the app has requested
- Your access to GitHub resources
Let's use an example to explain this.
GitHub user Alice logs into a third-party web application, ExampleApp, using their GitHub identity. During this process, Alice authorizes ExampleApp to perform actions on their behalf.
However, the activity ExampleApp is able to perform on Alice's behalf in GitHub is constrained by: the repositories on which ExampleApp is installed, the permissions ExampleApp has requested, and Alice's access to GitHub resources.
This means that, in order for ExampleApp to create an issue on Alice's behalf, in a repository called Repo A, all of the following must be true:
- ExampleApp's GitHub App requests write access to issues.
- A user having admin access for Repo A must have installed ExampleApp's GitHub App on Repo A.
- Alice must have read permission for Repo A. For information about which permissions are required to perform various activities, see "Repository permission levels for an organization."