# GitHub App

The GitHub App is how Upseam reads your repositories and opens pull requests.
To install it, see [Install the GitHub App](install.md).

## 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.                                                                                                    |
| Members (organization) | read         | List the organization's teams so you can pick a team as a reviewer in Routing. Without it you type the team name by hand.                    |

Upseam does not ask for Workflows, Actions, Administration or Secrets. Members
is the only organization permission, and it is read-only. When an installation
has not accepted it yet, GitHub asks the organization owner to approve the new
permission, and Routing keeps working with teams typed by hand.

## What it reads

- **Your code and lockfiles.** Upseam downloads the archive of a repository
  to find the affected code. The archive exists only in a temporary directory
  during a step; Upseam stores paths, lines and symbols, never code.
- **Pull requests and CI results.** It reads Dependabot and Renovate pull
  requests, and the checks and statuses of its own pull requests.
- **The dashboard issue.** It reads the checkboxes you tick.
- **Team names**, with the Members permission, for the Routing picker.

## What it writes

- **Commits to `upseam/*` branches.** Upseam's code refuses to create or
  update any other branch and to open a pull request from any other branch.
  It never pushes to your default branch, and it has no code that merges a
  pull request.
- **Pull requests** from those branches, and comments on them.
- **One dashboard issue** per repository that has something to report.
- **`repository_dispatch`** events, when fixes are generated in your GitHub
  Actions.

## Limits

> **Warning.** GitHub cannot narrow `contents: write` to a path or a branch.
> The limit to `upseam/*` is a rule in Upseam's code, not something GitHub
> enforces. Protect your default branch with a branch protection rule or a
> ruleset; it applies to the App unless you list the App as allowed to bypass
> it.

- Without the Workflows permission GitHub does not let the App change files
  in `.github/workflows`. The App cannot read your repository or organization
  secrets or change repository settings.
- Installation tokens are created for each use with the permissions the step
  needs, held in memory only, and expire after at most an hour, as GitHub
  sets.

:::cards Related resources

- [Threat model](threat-model.md)
  What the App can and cannot do, and what an attacker would get.
- [Security model](security.md)
  The patch gates and who runs what.
- [Uninstall Upseam](uninstall.md)
  What Upseam deletes when GitHub reports the removal.

:::