Install the GitHub App

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

Install

Open the Upseam install link from the Upseam site. It leads to GitHub's page for installing the App.
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.
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.

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.

Connect a model to get fix pull requests. See Connect a model.
Connect Slack for reports and approval buttons. See Slack.
Choose the default mode, ask or auto. See Delivery modes.

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.

Settings that are about your code, internal contracts and ignore rules, live in .github/upseam.yml 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.