# GitHub pull request reviews

The review bot on GitHub is the **DBGorilla** GitHub App.  Setup takes three
steps: install the App, connect the installation to your DBGorilla workspace,
and link each repository to the database it uses.  Reviews start after the second
step.  The third makes them database-aware.

[Pull request reviews](/docs/integrations/pull-request-reviews/) covers what a review
contains and what the connected review adds.

## 1. Install the GitHub App

You install the App on GitHub from either of two places.  Both open the same
screen:

- [github.com/apps/dbgorilla/installations/new](https://github.com/apps/dbgorilla/installations/new), or
- the Admin Portal in DBGorilla, under **Integrations**.  The **DBGorilla Review
  for GitHub** card has a **Connect GitHub** button.

On that screen you pick the account or organization to install into, then
either all repositories or a list you choose.  You can change the selection on
GitHub later.

The App asks for write access to repository contents, pull requests, issues and
commit statuses, and read access to metadata.  Writing pull requests and issues
is how it posts and updates its review comments.  Writing commit statuses is how
it publishes its check.  It subscribes to one event, `pull_request`, and acts
when a pull request is opened, reopened, marked ready for review, or updated
with new commits.  Pushing to a branch with an open pull request starts a
fresh review of that commit.

## 2. Connect the installation to your workspace

Return to DBGorilla and connect the installation from the same
**Integrations** card.  Only a workspace admin sees it.  DBGorilla checks that you
control the installation before linking it to your account.  This is the only way
an installation gets linked to a workspace.  Support cannot do it for you.

From here on, every pull request in the repositories you selected gets a review,
from the diff alone until the repository is linked to a database.

## 3. Link the repository to its database

This step needs a database connected to DBGorilla.  If you do not have one yet,
see [Connect a database](/docs/integrations/pull-request-reviews/#connect-a-database).

1. Open the component in DBGorilla.  This opens its **Metrics** tab.
2. Pick **Settings** from the tabs across the top.
3. Under **GitHub Repositories**, add the repository.

The card there explains the link: pull requests opened on a connected repository
are reviewed against this component's database.

If the card says GitHub is not connected, the App installation has not been
connected to this workspace yet.  Go back to step 2.

## Block merges on a failing review

The **DBGorilla Review** status fails on a blocking risk.  To stop such a pull
request from merging, add **DBGorilla Review** as a required status check in the
branch protection rule, or ruleset, for the branch you merge into.  A review that
could not run also fails the status, so a required check blocks the merge until
a later review passes.

## Turn it off

Three different actions turn reviews off, and they do different things.

Uninstalling the App on GitHub stops reviews at once.  DBGorilla deletes the
record linking that installation to your workspace.

Disconnecting the installation in the Admin Portal leaves the App installed on
GitHub but deletes the same link record, so DBGorilla no longer recognises the
installation and stops posting.  This is also how you move an installation to a
different workspace: disconnect, then connect again from the other one.  An
installation cannot be repointed in place.

Removing a repository from a component keeps reviews running on that repository,
but they drop back to the diff-only review.

None of these touch the comments DBGorilla has already posted.  Review comments,
inline comments and commit statuses on existing pull requests stay exactly as
they are.  If you want them gone, delete them on GitHub.