# Install the GitHub App

Installing Upseam works like installing Dependabot: install, pick
repositories, done. You need no YAML file and no secrets.

## Install

1. Open the Upseam install link from the Upseam site. It leads to GitHub's
   page for installing the App.
2. Choose the account or organization, then **All repositories** or **Only
   select repositories**. If you do not own the organization, GitHub sends
   the request to its owners.
3. GitHub returns you to the setup page, **Upseam is watching N
   repositories**. Sign in with GitHub to see it: Upseam shows an
   installation only to people GitHub lists as having access to it. Until
   GitHub's notice of the new installation reaches Upseam, the page says
   **Upseam is setting up**.

Upseam scans each selected repository once, right away, and records its SDKs,
versions and internal contracts. A repository gets the dashboard issue
**Upseam watches this repository** only when it has a finding that needs you,
a finding that waits for approval, a finding that is ready to fix or a setup
notice; a supported SDK or an
internal contract alone opens no issue. Until you connect a model, fixable
findings are listed there as ready to fix; see
[Without a model](models.md#without-a-model).

## Optional steps

The setup page offers three steps. You can skip them, but without a model
Upseam writes no fixes; it only lists what it would fix. See
[Without a model](models.md#without-a-model).

- **Connect a model** to get fix pull requests. See [Connect a model](models.md).
- **Connect Slack** for reports and approval buttons. See [Slack](slack.md).
- **Choose the default mode**, `ask` or `auto`. See
  [Delivery modes](delivery-modes.md).

## Settings page

The settings page of an installation has these sections: **Mode**, **New
capabilities**, **Repositories**, **Model**, **Generate in my GitHub Actions
(key stays in my secrets)**, **Slack** and **Disconnect**. Who can change
what is described in [Delivery modes](delivery-modes.md#who-can-change-the-mode).

Settings that are about your code, internal contracts and ignore rules, live
in [`.github/upseam.yml`](configuration.md) in the repository. Everything
else lives on the settings page. Each setting has one place.

## Permissions

| Permission      | Access       | Why                                                                                   |
| --------------- | ------------ | ------------------------------------------------------------------------------------- |
| Metadata        | read         | Basic access to the installation's repositories.                                     |
| Contents        | read & write | Read the code and lockfiles; write commits to `upseam/*` branches only; send `repository_dispatch` when fixes are generated in your Actions. |
| Pull requests   | read & write | Open and update Upseam's pull requests; read Dependabot and Renovate pull requests.   |
| Issues          | read & write | Keep the dashboard issue up to date and read its checkboxes.                         |
| Checks          | read         | Read your CI result.                                                                 |
| Commit statuses | read         | Read your CI result reported as statuses.                                            |

Upseam does not ask for Workflows, Actions, Administration, Secrets or
organization permissions. Without the Workflows permission GitHub does not let
the App change files in `.github/workflows`. Upseam never pushes to your
default branch; we still recommend protecting it.

## Uninstall

Uninstall the App from your GitHub settings; the **Disconnect** section of
the settings page links there. When GitHub reports the uninstall, Upseam
deletes the installation with its repositories, surfaces, findings, settings,
stored model key and Slack link. It keeps a removal marker with only the
installation id and the time of removal, so that late GitHub notices do not bring the installation
back. Internal records of queued work and received webhook deliveries are not
part of that deletion.

Uninstalling does not revoke the Slack bot token with Slack. To revoke it,
press **Disconnect Slack** before uninstalling, or remove the Upseam app from
your Slack workspace.