Skip to main content

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

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

​
Before you start

You need:
  • A Roboticks account and at least one project (create one at 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

1

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]
2

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]
3

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

Accept permissions

Review the permissions on the GitHub install screen and click Install. See Permissions for the exact scopes and why each is requested.
5

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

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

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

Org-widePer-repo
Setup costOne install, doneOne install + every new repo added manually
Future-proofNew repos pick up automaticallyNew repos require a configure step
Blast radius if you uninstallAll reposOnly selected repos
Recommended forTeams that standardise on RoboticksTrial / 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. 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 for how coverage rolls up across repos.
For a monorepo, you don’t need this — point one repo at one project and let path filters in roboticks.yaml carve it up.

​
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.
Uninstalling does not delete your data. To permanently delete a project’s data, use Settings → Project → Delete Project on the Roboticks dashboard.

​
Next

Permissions

The exact scopes the App requests, with justification per scope.

Webhooks

Events we subscribe to and the HMAC verification model.

Check Runs

What a passing or failing Check Run looks like on a PR.

Troubleshooting

Webhook 4xx errors, missing Check Runs, rate limits.