Permissions
Roboticks is built to the principle of least privilege. The App requests only the scopes it needs to read your code, post a Check Run, and comment on PRs. We do not request admin, we do not write to your code, and we do not read secrets.This is a complete list. If you see Roboticks asking for a scope that is not on this page, do not install — open a ticket at hello@roboticks.io and we’ll investigate.
Repository permissions
| Permission | Access | Why we need it |
|---|---|---|
| Contents | Read | Fetch roboticks/requirements.yaml, roboticks.yaml config, and the source tree at the SHA we’re testing. Read-only — we never push, branch, or tag. |
| Checks | Write | Create and update the Roboticks Check Run on each PR head SHA. This is the primary surface for coverage delta and pass/fail status. |
| Pull requests | Write | Post a single PR comment per PR with the traceability summary (opt-in per project). Also lets us mark conversations as resolved when a regression is fixed in a subsequent push. |
| Workflows | Read | Read existing GitHub Actions workflow definitions to detect conflicts and to support the “import from Actions” onboarding helper. We never modify workflows. |
| Metadata | Read | Mandatory baseline scope GitHub requires for every App — basic repo info, default branch, visibility. |
Organisation permissions
None requested.User permissions
None requested.What we deliberately do not request
| Scope | Why not |
|---|---|
| Contents (write) | Roboticks never modifies your source. Any test scaffolding suggested by the gap analysis is presented in the dashboard for a human to commit — we do not push it. |
| Administration | We do not need to manage repos, teams, or org settings. |
| Secrets / Actions secrets | We do not read CI secrets. Tokens used by the Roboticks runner are issued by the App at job time, scoped to the SHA, and expire on completion. |
| Single sign-on / SAML | Out of scope. SSO into the Roboticks dashboard is handled separately on Enterprise tiers. |
| Packages / Releases (write) | Evidence packs live in Roboticks-managed storage. We do not publish to GitHub Releases or Packages. |
| Issues (write) | Opening issues automatically is opinionated and noisy; we surface gaps and regressions in the dashboard and Check Run instead. |
Webhook events we subscribe to
| Event | Why |
|---|---|
installation | App installed, uninstalled, or suspended on an account. Lets us provision/de-provision the link to a Roboticks project. |
installation_repositories | Repos added or removed from an existing installation. Keeps the project ↔ repo mapping in sync. |
pull_request | The trigger for a PR-time test run. We handle opened, synchronize, reopened, ready_for_review. |
push | Triggers test runs for main / release branches per the project’s branch policy. |
workflow_run | Lets us mirror GitHub Actions outcomes if a customer prefers to run the job in their own Actions environment instead of a Roboticks runner. |
check_suite | GitHub may re-request a check suite when a user clicks Re-run. We respond by re-dispatching the job. |
Token model
Two distinct tokens are issued per installation:- App JWT — signed with the App’s private key (held only by Roboticks). Used to call
/app/installations/...endpoints. Expires after 10 minutes; rotated continuously. - Installation token — exchanged on demand via the App JWT. Scoped to the installation and the resources the installation can see. TTL: 1 hour. Cached server-side, never persisted to disk, never shipped to runners.
How we minimise blast radius
- No long-lived secrets shipped to client devices. The App private key never leaves the backend.
- Per-SHA token issuance. A runner that processes a stale job cannot replay its token against a different SHA.
- Audit log of every API call is exposed under Settings → Audit Log in the dashboard for paid tiers.
- HMAC-verified webhooks with replay protection. See Webhooks → Verification.
Reviewing what’s installed
In GitHub: Settings → Applications → Installed GitHub Apps → Roboticks → Configure. You can see the exact repos the App has access to and revoke any of them. In Roboticks: Settings → Integrations → GitHub App shows the installation, the linked project(s), the webhook secret rotation date, and a live “last webhook seen” timestamp.Next
Webhooks
HMAC verification, replay protection, payload examples.
Check Runs
The Check Run summary markdown with a sample.