Start
Install the GitHub App
What the Forseti GitHub App can and cannot do, the events it listens to, and how to change which repositories it sees.
Forseti is a GitHub App, not an OAuth app acting as you. It acts under its own identity, with permissions you can see and change in GitHub at any time, and tokens that are narrowed to one repository for each job.
Install
- Choose Connect GitHub on this site, then Authorize on GitHub, which signs you in.
- Pick the personal account or organisation.
- Choose All repositories (including future ones) or Only select repositories, then Install.
Forseti asks for no organisation-level permissions. Becoming the owner of a new Forseti workspace for an organisation needs an active admin of that organisation; members can then join it.
If your organisation requires owner approval for apps, GitHub sends the request to an owner and Forseti tells you it is waiting for approval.
Permissions
| Permission | Access | Why |
|---|---|---|
| Contents | Read | Read files around the diff, compare commits, and read .forseti.yaml and guidance files from the base commit. |
| Pull requests | Read & write | Read PRs and changed files; post the review with inline comments; edit the summary; reply to and resolve its own threads; request reviewers you choose. |
| Checks | Read & write | One check run per head commit with the depth, the estimate and the result. |
| Issues | Read & write | Receive @forseti commands in PR comments and acknowledge them with a reaction; read linked issues for the intent check. |
| Metadata | Read | Required by GitHub for every app. |
Not requested: write access to code, workflows, administration, members or any organisation permission. Forseti cannot push commits, change settings or merge. Fixes arrive as suggestion blocks that a person commits under their own name.
Settings in the dashboard shows a live checklist of these permissions for each installation, and flags any that are missing.
Webhook events
| Event | Used for |
|---|---|
pull_request | Opened, reopened, ready for review, new commits, base branch changed, converted to draft, closed |
issue_comment | Commands in PR comments |
pull_request_review_comment | Commands in finding threads, such as @forseti explain |
installation | Created, removed, suspended, permissions accepted |
installation_repositories | Repos added to or removed from the installation |
Every delivery is verified with GitHub's signature before anything else happens and recorded once, so a redelivered event never causes a second review. A sweeper asks GitHub for deliveries that never arrived and replays them.
Tokens and data
- Each review job gets an installation token scoped to the one repository and the permissions it needs.
- Diffs are fetched when a review runs and are not stored as a copy of your code.
- Findings keep only the few lines they quote. Switch off store snippets in Settings to keep none.
- Secrets are redacted, and secret files skipped, before any model call.
- Writes to GitHub are spaced out per installation to stay well inside GitHub's rate limits.
More in the FAQ and on the Security page.
Adding and removing repositories
Change the repository selection in GitHub: Settings → Applications → Installed GitHub Apps for a personal account, or the organisation's Settings → GitHub Apps, then Configure next to Forseti. Forseti hears about the change straight away. New repos are enabled automatically unless an owner has switched that off in Settings; removed repos stop being reviewed.
Owners and admins can also press Re-sync in Settings to re-read every installation's repositories from GitHub.
Suspending or uninstalling
Suspend or uninstall the app from the same GitHub page. Forseti stops reviewing that installation's repos at once. To remove the workspace itself, an owner can delete it under Settings by typing its name.