> ## 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.

# GitHub App Permissions

> Every scope the Roboticks GitHub App requests, with justification — and what we deliberately do not request.

# 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.

<Info>
  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](mailto:hello@roboticks.io) and we'll investigate.
</Info>

## 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.                                    |

Full event payload handling lives in [Webhooks](/github-app/webhooks).

## Token model

Two distinct tokens are issued per installation:

1. **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.
2. **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.

Runners do not see installation tokens. The runner is handed a short-lived job token issued by the Roboticks backend that is bound to the specific SHA being tested and revoked on job completion.

```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
    K["App private key<br/>(Roboticks-held)"] --> JWT["App JWT<br/>10 min"]
    JWT --> IT["Installation token<br/>1 hour"]
    IT --> CR["Check Runs API"]
    IT --> RD["Repo contents read"]
    BE["Backend"] --> RT["Runner job token<br/>SHA-bound, single-use"]
    RT --> Run["Runner"]
```

## 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](/github-app/webhooks#hmac-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

<CardGroup cols={2}>
  <Card title="Webhooks" icon="bolt" href="/github-app/webhooks">
    HMAC verification, replay protection, payload examples.
  </Card>

  <Card title="Check Runs" icon="circle-check" href="/github-app/check-runs">
    The Check Run summary markdown with a sample.
  </Card>
</CardGroup>