GitHub App

Early access

Anyone can install the GitHub App. It's free during early access, and SHAPI asks before anything is charged. Tell us what breaks: open an issue or email sri@shapi.dev.

What it does

• On every push to your default branch, SHAPI downloads that commit with a short-lived token that can only read that one repository. It builds the api.lock and posts a SHAPI check on the commit: neutral by default, with an annotation on each affected line. A push that GitHub delivers late, after a newer one (for example after an outage), is not scanned: the newer push's commit is the branch as it is now.
• For each affected call site with a fix recipe, it verifies the fix in an isolated sandbox and opens a pull request with the fix and its contract test.
• When an advisory is added or changed, it re-matches every installed repository's stored api.lock and opens PRs where the new advisory hits.
• A SHAPI Dashboard issue in each repository lists open fix PRs, fixes waiting for a limit, fixes whose branch you pushed to (SHAPI never overwrites it; delete the branch to let it open the fix), fixes you closed, changes that need a manual fix, and upcoming deadlines.

Permissions

Permission	Why
Contents: read and write	Read code to scan it; push fix branches. It cannot change workflow files.
Pull requests: read and write	Open and update fix PRs.
Checks: read and write	Post the SHAPI check on commits.
Issues: read and write	The SHAPI Dashboard issue.
Metadata: read	Required by GitHub for every app.

Events: push, pull_request, issues, repository (SHAPI stops on an archived repository and scans it again once it is unarchived), plus the installation events every app receives.

Slack alerts

Paste a Slack incoming webhook link under Settings in the web app, and SHAPI posts to that channel when a repository gets a new affected call site. That happens after a push, or when a new advisory hits code SHAPI already mapped. Each message lists the advisories with their severity, links to the exact lines, and the deadlines. A call site that was already affected isn't announced again. Use Send a test message to check the link.

Noise controls

• At most 2 new PRs per hour and 10 open at once per repository, most urgent first. Both are configurable in the web app.
• One PR per advisory: it fixes every affected call site in the repository, with a contract test for each, and reruns update the same PR instead of opening duplicates. A call site SHAPI can't fix is listed in the PR and on the dashboard.
• A PR you close without merging stays closed. Tick "open it again" on the dashboard if you change your mind.
• The shapi:stop label freezes a PR. Pausing a repository, from the dashboard or the web app, stops all changes.
• The check is neutral by default and never blocks a merge, unless you turn on Fail the SHAPI check.

The web app

Sign in with GitHub to see each repository's latest scan, its findings with links to the exact lines, fix PR history and recent scans. That is also where you change the limits, the check behavior and the Claude opt-in, and where you pause a repository. You see only the repositories you can open on GitHub. Pausing one needs write access to it, and the account's settings and billing need an account admin: the owner of a personal account, or for an organization someone who is admin on every repository SHAPI covers there. SHAPI keeps no GitHub user token: it reads who you are, which installations you can access and your permission on each of their repositories, then discards the token. So that access is what GitHub said when you signed in: a repository added to the installation afterwards appears when you sign in again (the web app tells account admins), and until then it doesn't count against an admin.

Plans

Public repositories and one private repository are free. Each additional private repository has a monthly fee, shown in the web app before you pay, and it's free during early access. Adding private repositories never raises the bill on its own: the web app asks first.