Integrations
GitHub
Verified against Soffi ·
- Status
- Available
- Availability
- Every organization
- Required role
- Admin
GitHub is the one integration Soffi can't work without. Your code comes from it, and everything you make in Soffi goes back to it as a pull request. There are two separate connections, and it helps to keep them apart:
- The Soffi GitHub app, installed once on the GitHub organization that owns your repositories. This is the Organization's connection. It's how Soffi reads your code and opens pull requests, and only an Admin or the Owner can set it up.
- Your own GitHub account, which each person can link to Soffi. It's optional. When you've linked it and have write access to a repository, the pull requests you Ship open under your own name instead of as Soffi. See From Workspace to pull request and What linking your account grants.
Most teams install the app during Set up your organization. Afterwards it lives in Settings, under GitHub app. Editors can open that page and see how things stand; only Admins and the Owner can change anything there.
What the app can access
Soffi asks GitHub for only what it uses, and only on the repositories you grant it:
| Permission | Why Soffi needs it |
|---|---|
| Contents, read and write | Reading your code so Soffi can run your app, and pushing each Workspace's work to its branch: a new one, or the branch of the pull request it was opened from. |
| Pull requests, read and write | Opening and updating the pull requests you Ship, commenting on pull requests, and reading them so they can be previewed and summarized. |
| Actions, read | Reading CI runs and their logs, so Soffi can tell you whether a Workspace's pull request passed and why it failed. |
| Metadata, read | Basic repository details, such as names and default branches. GitHub requires it for every app. |
If you don't approve the Actions permission, everything else still works, and Soffi tells you when it can't read CI.
What linking your account grants
Linking your own account authorizes the Soffi GitHub app to act as you. That access is bounded twice: it covers only repositories where your organization installed the app, and only what you can already do on them yourself, so it never reaches further than the app or you could alone. Soffi uses it for one thing, opening the pull requests you Ship under your name. Reading code, pushing branches, and everything else go through the app.
The access Soffi holds for your account is encrypted at rest. To remove it, choose Disconnect next to GitHub in your account settings. Disconnecting deletes the access Soffi holds; to revoke it on GitHub's side as well, remove Soffi from your GitHub account's authorized apps.
Soffi's work reaches your repositories as branches and pull requests, and Soffi never merges. Merging stays with your team, through your normal review and CI.
To see exactly what your installation granted, open GitHub app, go to Repositories, and expand a repository. Permissions Granted lists each permission and its level.
Choosing which repositories Soffi sees
When you install the app, GitHub asks whether to grant it all repositories or only the ones you select. Choosing specific repositories is the safer default: grant your app's repositories and the ones it depends on, such as a design system or a shared config, and nothing else.
To change the selection later, use Configure repos on GitHub on the Repositories tab, or Manage on GitHub on any repository. The change happens on GitHub. Back in Soffi, choose Sync Repositories to pick it up.
The Repositories tab lists repositories with the app installed first, then Other Repositories: ones Soffi knows about but that the app can't access, marked No App.
Pull request comments
When a pull request opens in a connected repository, Soffi posts a summary comment on it. See PRs opened outside Soffi. AI Summary Comments is on by default. An Admin can turn it off for the whole Organization on the Advanced tab, or for one repository from its settings on the Repositories tab.
Removing access
There are three levels, from narrowest to complete:
- Remove one repository from Soffi. On the Repositories tab, choose Remove from Soffi on the repository. Soffi won't remove a repository that a Project still uses, so delete those Projects first. Removing it can't be undone, and the archived work built on it in Soffi goes with it. Nothing changes on GitHub.
- Disconnect the GitHub organization. On the Advanced tab, Disconnect unlinks the GitHub organization from your Soffi Organization. The app stays installed on GitHub.
- Uninstall the app on GitHub. This is what revokes Soffi's access to your repositories. Do it from your GitHub organization's installed apps settings.
Disconnect & sign out on the Advanced tab is different. It clears only your own linked GitHub account and signs you out, so someone else can sign in and finish setup.