When you click the “sign in” button on plz.review, 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 plz.review 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 plz.review 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 plz.review 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.
No permissions beyond those required for OAuth are requested by the app.
The auth token provided via cookie to plz.review 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 plz.review 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.
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.
- Contents (Read and write) - Repository contents, commits, branches, downloads, releases, and merges.This allows us to merge PRs from the plz UI.
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 plz.review 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.
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
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 plz.review access to your repositories) your GitHub data will no longer be accessible to us.
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.