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

# Installing the GitHub App

> Connect a Roboticks project to one or more GitHub repositories. Covers org-wide and per-repo installs, the OAuth callback, and the multi-installation model.

# Installing the GitHub App

The Roboticks GitHub App is the only piece of infrastructure that lives inside your repository's permission boundary. It receives webhooks, posts Check Runs, and reads the files Roboticks needs to drive a test run. Nothing else.

<Info>
  **One project, many repos.** A single Roboticks project can be linked to many GitHub repositories. The reverse — one repository pointing to many projects — is not supported; each repo belongs to exactly one Roboticks project at a time.
</Info>

## Before you start

You need:

* A Roboticks account and at least one project (create one at [app.roboticks.io](https://app.roboticks.io)).
* **Admin** permission on the GitHub organisation or repository you intend to connect. Personal accounts work too.
* A network path from your repo's webhook delivery to `https://api.roboticks.io/api/v1/github/webhooks` — this is the public internet for GitHub.com customers and a static IP allowlist for GHES.

## The install flow

<Steps>
  <Step title="Start from the Roboticks dashboard">
    Open the project, then go to **Settings → Integrations → GitHub App** and click **Install on GitHub**. This anchors the install to the project — if you start from GitHub directly, you'll have an extra step to map the installation afterwards.

    *\[Screenshot needed: Settings → Integrations → GitHub App panel with "Install on GitHub" button]*
  </Step>

  <Step title="Choose the GitHub account">
    GitHub redirects you to the App install page. Pick the org or user that owns the repos you want to connect.

    *\[Screenshot needed: GitHub "Install Roboticks" account picker]*
  </Step>

  <Step title="Pick repositories">
    Choose **All repositories** for an org-wide install (recommended for teams that intend to standardise on Roboticks across the org) or **Only select repositories** for a curated subset.

    <Tabs>
      <Tab title="Org-wide">
        Picks up every existing and future repo. Best when Roboticks is the org's standard test CI. You can still scope which repos belong to which Roboticks project on the dashboard side.
      </Tab>

      <Tab title="Per-repo">
        Pick repos one by one. Best when only a handful of repos are robotics-related, or when you want a gradual rollout. Add more later from **GitHub → Settings → Applications → Roboticks → Configure**.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Accept permissions">
    Review the permissions on the GitHub install screen and click **Install**. See [Permissions](/github-app/permissions) for the exact scopes and why each is requested.
  </Step>

  <Step title="Callback to Roboticks">
    GitHub redirects to `https://app.roboticks.io/integrations/github/callback?installation_id=...`. The dashboard records the installation and links it to the project you started from.
  </Step>

  <Step title="Link repositories to the project">
    For each repo in the installation, choose which Roboticks project it belongs to. By default they all link to the project you started from; you can split them across projects from **Settings → Repositories**.

    *\[Screenshot needed: Repository → Project mapping table]*
  </Step>
</Steps>

<Check>
  You should now see each connected repository under **Settings → Repositories** with status **Connected**. The first webhook delivery — typically the `installation` event itself — lands within a second of the install completing.
</Check>

## Org-wide vs per-repo: which to pick

|                               | **Org-wide**                        | **Per-repo**                                |
| ----------------------------- | ----------------------------------- | ------------------------------------------- |
| Setup cost                    | One install, done                   | One install + every new repo added manually |
| Future-proof                  | New repos pick up automatically     | New repos require a configure step          |
| Blast radius if you uninstall | All repos                           | Only selected repos                         |
| Recommended for               | Teams that standardise on Roboticks | Trial / pilot installs, mixed orgs          |

Both modes use the **same** permissions; the GitHub-side scope is just `all` vs `selected`. You can switch later in **GitHub → Settings → Applications → Roboticks**.

## The many-to-one repo → project model

Each Roboticks **project** owns a set of GitHub repositories. A repo cannot be shared across projects — if you need that, factor the shared code into a third repo and connect it to its own project.

```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
    P1["Project: warehouse-amr"] --> R1["repo: amr-stack"]
    P1 --> R2["repo: amr-launch"]
    P1 --> R3["repo: amr-simulation"]
    P2["Project: dock-picker"] --> R4["repo: picker-perception"]
    P2 --> R5["repo: picker-control"]
```

One of the repos in a project is designated the **default repo** — this is where Roboticks looks for `roboticks/requirements.yaml`, the inline configuration, and the manifest. See [Multi-repo projects](/traceability/multi-repo) for how coverage rolls up across repos.

<Tip>
  For a monorepo, you don't need this — point one repo at one project and let path filters in `roboticks.yaml` carve it up.
</Tip>

## Multiple installations on one org

A single GitHub org can host multiple Roboticks installations — for example, a "production" installation that posts blocking Check Runs and a "staging" installation that posts neutral ones. Each installation is independent and has its own webhook secret. Most teams will never need this; it exists for regulated customers who segregate environments.

## Uninstalling

From **GitHub → Settings → Applications → Roboticks → Uninstall**, or from the Roboticks dashboard at **Settings → Integrations → GitHub App → Disconnect**. Either path:

* Stops new webhooks immediately.
* Leaves historical evidence packs, requirements, and traceability data intact in Roboticks (you can re-install later and resume).
* Releases the installation token so the App can no longer call GitHub on your behalf.

<Warning>
  Uninstalling does not delete your data. To permanently delete a project's data, use **Settings → Project → Delete Project** on the Roboticks dashboard.
</Warning>

## Next

<CardGroup cols={2}>
  <Card title="Permissions" icon="lock" href="/github-app/permissions">
    The exact scopes the App requests, with justification per scope.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/github-app/webhooks">
    Events we subscribe to and the HMAC verification model.
  </Card>

  <Card title="Check Runs" icon="circle-check" href="/github-app/check-runs">
    What a passing or failing Check Run looks like on a PR.
  </Card>

  <Card title="Troubleshooting" icon="bug" href="/github-app/troubleshooting">
    Webhook 4xx errors, missing Check Runs, rate limits.
  </Card>
</CardGroup>