Documentation Index
Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
Use this file to discover all available pages before exploring further.
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.