Skip to content
upseamdocs
Open the App GitHub

GitHub App

The permissions the Upseam GitHub App asks for, what it reads, what it writes and what it can never do.

On this page

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

#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.

Related resources

Threat modelWhat the App can and cannot do, and what an attacker would get.Security modelThe patch gates and who runs what.Uninstall UpseamWhat Upseam deletes when GitHub reports the removal.