Why TofuPilot Needs Administration: write
The TofuPilot GitHub App now requests the Administration: write repository permission. This guide explains why we ask for it ahead of an upcoming feature, what it enables, our security model, and the alternatives if you'd rather not grant it.
Why the new permission
The upcoming Stations v2.0 ships a new procedure-creation workflow that takes you from procedure to deployed-on-station in two steps. Since many users don't have a repository yet, or are new to TofuPilot Framework / OpenHTF, we'll provide ready-to-go templates that get cloned into your account before deploying.
GitHub requires Administration: write for any third-party app to create a repository on a user's behalf. We have no other write operations beyond this one. The same permission is requested by leading developer platforms for the same reason — it's the only mechanism GitHub exposes for creating a repository from a template.
Security model
We take this permission seriously. Our protections include:
- No other write routes. Our APIs expose no GitHub write operations beyond this single template-clone call, scoped to creating one new repository.
- Strict tenant isolation. Connection records are isolated per organization at the database level — even an authenticated user from one organization cannot read another organization's data.
- Restricted to owners and admins. Managing connections (create / update / delete) is restricted to organization owners and admins.
- Secrets kept out of the database. The GitHub App private key required to mint installation tokens lives in our cloud provider's encrypted secret store, not in our application database. A database leak alone does not grant access to your GitHub account.
If you'd rather not grant it
You have three options:
1. Don't accept the permission
The Clone Template feature won't work, but everything else (importing existing repos, auto-deploy, webhooks, operator UI) continues to work normally. You can create a repository manually on GitHub, then use the Import flow.
2. Scope to selected repositories
When re-accepting the permissions, pick Only select repositories instead of All repositories. This limits the App's access to repositories you explicitly pick.
After we clone a template, you may need to manually add the new repository to the App's allowed list before auto-deploy starts working on it.
3. Self-hosted or dedicated managed deployment
Configure your own GitHub App with whatever permissions fit your security policy. TofuPilot adapts to the permissions available: features that need missing permissions are hidden, everything else continues to work normally.
How to grant or scope the permission
- In TofuPilot, open your organization's New Procedure page. If the permission is missing, an in-app banner will appear with a Grant permission on GitHub button once the feature ships.
- Click the button. You're redirected to your GitHub installation's permissions page.
- Choose Only select repositories if you want to scope the App tightly. Otherwise, All repositories is fine.
- Click Accept new permissions. You're returned to TofuPilot, and the Clone Template form unlocks automatically.
Approval takes about 30 seconds.
What we use this permission for
We use Administration: write only to call GitHub's "create a repository from a template" API during the Clone Template flow. Every API call is logged in your GitHub audit log so you can verify exactly what we do.
We never delete, transfer, archive, or modify settings on existing repositories.
Frequently asked questions
Can you implement template clone without this permission?
Not on GitHub. GitHub does not offer a narrower scope. Every platform that lets you clone a template into a new repository requests the same permission for the same purpose.
What happens if I revoke the permission later?
Revoke it whenever you want from your GitHub install settings. Clone Template stops working immediately; everything else keeps working normally. Repositories created before the revoke are unaffected.
Does this give TofuPilot access to my private code?
Only for repositories the App is installed on. With Only select repositories, you control exactly which ones. With All repositories, the App sees everything in the account it's installed on. Read access to repository contents is governed by a separate permission TofuPilot has had since the beginning — Administration: write is solely about creating new repositories.