Manage the private GitHub App installation

Outcome

You can manage the private prpl-private GitHub App installation on GitHub — add or remove repositories, review permission updates, suspend, uninstall, and recover — and you know exactly what the App does and does not control in prpl.

What the App does: it powers automated review of Defend pull requests. When prpl opens a patch PR (branches named prpl/defend/…) on a repository where the App is installed, the App reviews the diff and posts advisory comments, and it responds to /prpl commands in PR comments (/prpl review, /prpl depth, /prpl autofix, /prpl dismiss, /prpl help). It is advisory only — it cannot merge, change branch protection, or grant itself more permissions. Defend pull requests themselves are opened with your stored GitHub token, not by the App, so App state never blocks PR creation.

Who can do it

prpl-private is a private GitHub App. GitHub only allows a private App to be installed on the account that owns the App — no other user or organization is offered the install flow. In practice:

• Installation management (repositories, suspend, uninstall) happens on GitHub, by an admin of the account where the App is installed — the App's owning account.
• App configuration (permissions, webhook, credentials) at github.com/settings/apps/prpl-private is visible only to the App's owning account — for a hosted prpl deployment that is the operator, not you.
• Your prpl role (mapped owner or site administrator) has no effect on GitHub's side; what matters is your GitHub permission on the installing account.

If your organization is not the App's owning account, you cannot install or manage it yourself — ask the operator who owns the App.

Before you begin

• You have GitHub admin rights on the account where the App is (or will be) installed.
• You know which repositories prpl scans — the review only fires on repositories included in the installation's repository access.
• Suspending or uninstalling has an immediate effect: Defend pull requests on affected repositories stop receiving automated review until access is restored. Scans, findings, and PR creation in prpl continue to work.

Steps

1. Install (first time). Open github.com/apps/prpl-private/installations/new, pick the target account, and choose All repositories or Only select repositories. See Install the private prpl Defender GitHub App for the full first-install walkthrough.
2. Open the installation settings. On GitHub go to Settings → Applications → Installed GitHub Apps (for an organization: Organization settings → GitHub Apps) and select Configure next to prpl-private.

3. Add or remove repositories. Under Repository access, switch between All repositories and Only select repositories, or edit the selected list, then select Save. prpl learns of the change from GitHub's webhook and enables or disables review for those repositories accordingly.

4. Review permission updates. When the App's requested permissions change, GitHub marks the installation as having new permissions requested and emails the installing admins. Open the installation page and accept the new permissions — until you do, the App keeps running with its old permissions. prpl records the acceptance and resumes normally.
5. Suspend, if you need a pause. On the installation page, use Suspend (in the danger zone). GitHub blocks all App access to your resources; prpl marks the installation suspended and Defend PR reviews stop. Unsuspend restores it with the repository selection intact.
6. Uninstall, if you need removal. Use Uninstall on the installation page. GitHub deletes the installation and notifies prpl, which marks it deleted. Repository selections do not survive an uninstall.
7. Recover. Reinstall from the installation link and re-select repositories. Only the App's owning account is offered this flow — that is the recovery boundary for a private App.

Verification

• GitHub lists prpl-private under Installed GitHub Apps with the repository access you chose.
• On the next Defend pull request in a covered repository, the App posts its review; commenting /prpl help on such a PR gets a command summary back.
• After a suspend or uninstall, new Defend PRs receive no App review — confirming the state change took effect.

Troubleshooting

• The install page says the App is unavailable, or you never see an install option. The App is private: GitHub refuses installation for any account other than the App's owner. This is a GitHub restriction, not a prpl setting — contact the operator who owns the App.
• Defend PRs get no review. Check, in order: the repository is included in the installation's Repository access; the installation is not suspended; the App was not uninstalled. Any of the three silently stops reviews while everything else in prpl keeps working.
• Reviews stopped after a permission change. A pending permission request does not stop the App, but a suspend issued alongside it does. Accept the new permissions on the installation page and check the suspend state.
• You uninstalled by accident. Reinstall from the installation link and re-select repositories. Nothing in prpl is lost — scans, findings, and PR history are unaffected; only the review coverage lapsed.

Next step

With review coverage in place, walk the patch pathway end to end: Generate and review patches with Defend and Review and approve a Defend pull request. For token-versus-App boundaries, see GitHub authentication and permissions reference.