Authorizing GitHub Apps

You can authorize a GitHub App to retrieve information about your GitHub account and to make changes on your behalf.

In this article

About authorizing GitHub Apps

Applications that are not owned by you, your organization, or GitHub Marketplace may need to verify your GitHub identity or interact with GitHub on your behalf. These applications can request authorization for a GitHub App to perform these actions. If an application requests authorization, it will redirect you to a GitHub page prompting you to authorize the app.

When authorizing the GitHub App, you should ensure you trust the application owner and review the information that the application wants to access. During authorization, you'll be prompted to grant the GitHub App permission to do all of the following:

  • Verify your GitHub identity: When authorized, the GitHub App will be able to retrieve your public GitHub profile. The app may also be able to retrieve some private account information. During the authorization process, GitHub will tell you which account information the GitHub App will be able to access.
  • Know which resources you can access: When authorized, the GitHub App will be able to determine which resources you can access that the app can also access. The app may use this, for example, so that it can show you an appropriate list of repositories.
  • Act on your behalf: When authorized, the application may perform tasks on GitHub on your behalf. This might include creating an issue or commenting on a pull request. For more information, see About GitHub Apps acting on your behalf.

You can review and revoke your authorization at any time. For more information, see Reviewing and revoking authorization of GitHub Apps.

Note

If your organization uses SAML SSO and you cannot see your organization's resources after you authorize a GitHub App, you may need to reauthorize the app after starting an active SAML session for your organization. For more information, see SAML and GitHub Apps.

About GitHub Apps acting on your behalf

Once you authorize a GitHub App, the app can 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 can only do things that both you and the app have permission to do. For example, if you have write access to a repository but the GitHub App only has read access, then the app can only read the contents of the repository even when it is acting on your behalf. Similarly, if you have access to repositories A and B, and the GitHub App has access to repositories B and C, then the app can only access repository B when acting on your behalf. For more information about the permissions granted to a GitHub App, see Difference between authorization and installation.

When an app acts on your behalf, it will attribute the activity to you in conjunction with the app. For example, if the app posts a comment on your behalf, the GitHub UI will show your avatar photo along with the app's identicon badge as the author of the issue.

Screenshot of a comment that has a user avatar with an overlaid app identicon badge. The avatar is highlighted with an orange outline.

Similarly, if the activity triggers a corresponding entry in the audit logs and security logs, the logs will list you as the actor but will state that the "programmatic_access_type" is "GitHub App user-to-server token".

Difference between authorization and installation

When you install a GitHub App on your account or organization, you grant the app permission to access the organization and repository resources that it requested. You also specify which repositories the app can access. During the installation process, the GitHub App will indicate which repository and organization permissions you are granting. For more information about what different permissions enable a GitHub App to do, see "Choosing permissions for a GitHub App."

For example, you might grant the GitHub App permission to read repository metadata and write issues, and you might grant the GitHub App access to all of your repositories.

Screenshot of the page to install a GitHub App. The app is requesting read access to metadata and write access to issues. The app can also request user authorization for read access to emails and write access to gists.

When you authorize a GitHub App, you grant the app access to your GitHub account, based on the account permissions the app requested. During the authorization process, the app will indicate which resources the app can access on your account. When you authorize a GitHub App, you also grant the app permission to act on your behalf.

For example, you might grant the GitHub App permission to read your email addresses and write gists.

Screenshot of the page to authorize a GitHub App. The app is requesting read access to email and write access to gists.

You can install a GitHub App without authorizing the app. Similarly, you can authorize the app without installing the app.

For more information about installation, see Installing a GitHub App from a third party, Installing a GitHub App from GitHub Marketplace for your personal account and Installing a GitHub App from GitHub Marketplace for your organizations.