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 and replies in finding threads, such as @forseti explain; a reply makes Forseti look at the finding again |
pull_request_review_thread | A person resolving a finding's thread (Forseti looks at the finding again) |
check_run, check_suite | The Re-run button on Forseti's check: a commit not reviewed yet is reviewed; on one already reviewed, the summary and the check are refreshed, at no charge |
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. If you do not reinstall it within 30 days, Forseti erases the workspace's stored data. To remove the workspace now, an owner can delete it under Settings by typing its name; its reviews, findings, policies and members are erased within a few hours, and a member who belongs to no other workspace loses their Forseti sign-in account too. Reinstalling the app on the same GitHub account inside the 30 days cancels the erasure and brings the workspace back as it was. Billing records are kept for tax law.