GitHub
Last updated
Last updated
uses GitHub OAuth for user authentication, and a GitHub App for managing access to resources on GitHub. For background on how these work, see .
The sign-in process uses the GitHub web application OAuth flow. This is a typical “sign in with GitHub” approach to authentication, and is depicted below:
No permissions beyond those required for OAuth are requested by the app.
At this point we have not been granted any permissions to access your resources. Accessing repositories and other GitHub resources on your behalf requires you to “install” the app. This can happen at the user/organization level, or at the level of specific repositories owned by you or your organizations.
Once the app has been granted access to certain repositories via the installation process, we can access repository metadata, code, pull requests, checks, etc. See below for more details on each of the resources where access is requested.
With a few exceptions noted below, we do not store your GitHub data on our servers. In general we do not store any of the following in resting data stores:
Access tokens
Source code
Repository metadata
Things we do store include:
Data generated by users within the app that is reflected in GitHub, e.g. review feedback. Feedback can be tied for a file resource (file name) or a line number in a file.
References to GitHub resources, e.g. commit SHAs referencing Git commits, pull request numbers, etc.
Excerpts of up to 4 lines of code per review comment, which provide context for feedback from reviewers and allow snappy display.
GitHub Action statuses and outcomes.
GitHub resources cached by our servers for up to an hour to improve latency and performance.
When you click the “sign in” button on , you’re redirected to GitHub which requests permission to share with us: 1) your GitHub identity, and 2) the GitHub resources to which you have access. Note that access to those resources is not being requested yet, only to know which resources you can access. We also request permission for to act on your behalf, insofar as the specific permissions you later grant will allow.
The authorization screen for granting these permissions is shown below:
Once you’ve authorized in this way, GitHub provides us with a user auth token, which is then returned to your browser as a cookie. Each time a request to servers takes place, that token is included by your browser. Importantly the app does not store this token in any resting data store. It is stored on your computer as a cookie, and is only used in a transient way by the app.
The auth token provided via cookie to is passed along to the GitHub API when we need to access GitHub resources. These kinds of requests are known as user-to-server requests, and are depicted below:
User-to-server requests are made by on your behalf. Only resources you’re authorized to access will be returned by the GitHub API. This ensures that your GitHub data will never be accessible to our other users who are not authorized.
The process of installing the app can be initiated from 1) the organization drop-down on the review list page, 2) from the GitHub page, or 3) from the GitHub organization settings page (accessible from the GitHub page.)
The authorization page for installing for personal repositories is shown below:
The following permissions are requested for organizations installing :
(Read-only) - Organization members and teams
The following permissions are requested for repositories where is installed:
(Read-only) - Checks on code.
(Read and write) - Repository contents, commits, branches, downloads, releases, and merges.
GitHub’s permissions around repo “contents" are quite coarse grained. of API endpoints categorized under that scope. The specific write endpoints that we use are:
(:write)
(:write) (:write) (:write)
These permissions allow us to manage stacks of reviews (e.g. rebasing on top of a modified base PR) and allow to interface with your Git repo.
(Read-only) - Search repositories, list collaborators, and access repository metadata.
(Read and write) - Pull requests and related comments, assignees, labels, milestones, and merges.
(Read and write) - Update GitHub Action workflow files.
While most GitHub resource access happens via the user-to-server flow described above, we may also access resources outside of the normal user flow. This can happen, for example, when is notified by GitHub of some event via a webhook. In this case there’s no user auth token involved and so we must use a different kind of token. As depicted below, a token specific to the relevant installation is minted and then passed to the GitHub API when accessing resources: The installation auth token is specific to a particular repository, user or organization installation. This token is minted on demand and the app does not store this token in any resting data store.
This means that any unauthorized access to our data stores will result in minimal exposure of sensitive information. It also means that if you uninstall the app (i.e. revoke access to your repositories) your GitHub data will no longer be accessible to us.