GitHub

plz.review uses GitHub OAuth for user authentication, and a GitHub App for managing access to resources on GitHub. For background on how these work, see Authorizing GitHub Apps.

OAuth sign in

The plz.review 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:

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.

User permissions

No permissions beyond those required for OAuth are requested by the app.

User-to-server requests

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.

App installation

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.

The process of installing the app can be initiated from 1) the organization drop-down on the plz.review review list page, 2) from the GitHub user installation settings page, or 3) from the GitHub organization settings page (accessible from the GitHub user organization settings page.)

The authorization page for installing plz.review for personal repositories is shown below:

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.

Organization permissions

The following permissions are requested for organizations installing plz.review:

• Members (Read-only) - Organization members and teams

Repository permissions

The following permissions are requested for repositories where plz.review is installed:

• Checks (Read-only) - Checks on code.

• Contents (Read and write) - Repository contents, commits, branches, downloads, releases, and merges.

  GitHub’s permissions around repo “contents" are quite coarse grained. This is the list of API endpoints categorized under that scope. The specific write endpoints that we use are:

  PUT /repos/:owner/:repo/pulls/:pull_number/merge (:write)

  This allows us to merge PRs from the plz UI.

  POST /repos/:owner/:repo/git/commits (:write) POST /repos/:owner/:repo/git/refs (:write) PATCH /repos/:owner/:repo/git/refs/:ref (:write)

  These permissions allow us to manage stacks of reviews (e.g. rebasing on top of a modified base PR) and allow the CLI to interface with your Git repo.

• Metadata (Read-only) - Search repositories, list collaborators, and access repository metadata.

• Pull requests (Read and write) - Pull requests and related comments, assignees, labels, milestones, and merges.

• Workflows (Read and write) - Update GitHub Action workflow files.

Server-to-server request flow

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.

Data retention

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.