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.

​
rbtk github

The GitHub App is the #1 integration — it’s how PRs become Check Runs and how requirements get linked to commits. The github group is the CLI surface around it. The dashboard is faster for the first install; the CLI shines for scripting (e.g., bulk linking after a repo migration). 
rbtk github
├── link        # Link a GitHub repo to the current Roboticks project
├── status      # Show current GitHub App install + per-repo link status
└── unlink      # Detach a repo from the current project
The GitHub App itself is installed through the GitHub UI — rbtk github doesn’t install the App, only links already-installed repos to projects. See GitHub App → Installation for the install flow.

​
rbtk github link

Link a repository to the current Roboticks project. The GitHub App must already be installed on the repo (or its parent org). 
rbtk github link --repo acme/warehouse
rbtk github link --repo acme/warehouse --branch main --watch-prs all
FlagDescription
--repo <owner/name>GitHub repo (required)
--branch <ref>Default branch for release evidence (auto-detected if omitted)
--watch-prs all|labeled|noneWhich PRs trigger Check Runs. labeled waits for a roboticks label. Default: all.
--block-merge / --no-block-mergeWhether the Roboticks Check Run is required for merge. Default: --no-block-merge (advisory).

​
Examples

# Wire one repo
rbtk github link --repo acme/warehouse

# Wire many in a loop
for repo in api worker robot-firmware; do
  rbtk github link --repo acme/$repo
done

# Block-merge for safety-critical
rbtk github link --repo acme/robot-firmware --block-merge
After linking, push a commit and a Check Run named Roboticks appears within ~30 s.

​
rbtk github status

Show GitHub App install status and the project’s linked repos. 
rbtk github status

GITHUB APP   installed on org acme (App ID 412345, installation 9876543)
SCOPES       contents:read · checks:write · pull_requests:write · metadata:read

LINKED REPOS (3)
  REPO                STATUS    DEFAULT BRANCH   WATCH PRS   BLOCK MERGE
  acme/warehouse      OK        main             all         no
  acme/api            OK        main             labeled     no
  acme/robot-fw       OK        develop          all         yes

LAST WEBHOOK         42s ago (push to acme/warehouse refs/heads/main)
--output json returns the full record including webhook signing secret rotation timestamps.

​
Per-repo deep dive

rbtk github status --repo acme/robot-firmware

REPO              acme/robot-firmware
PROJECT           warehouse
DEFAULT BRANCH    develop
WATCH PRS         all
BLOCK MERGE       yes
WEBHOOK DELIVERIES
  Last 24h: 142 (140 ok · 2 retried · 0 failed)
LAST CHECK RUN
  PR #214 · refs/heads/feat/new-arm · FAIL (411/412 tests, REQ-051 uncovered)

​
rbtk github unlink

Detach a repo from the current project. The GitHub App stays installed; only the link to this project is removed. 
rbtk github unlink --repo acme/warehouse
FlagDescription
--repo <owner/name>GitHub repo (required)
--purge-historyAlso delete historical Check Runs and webhook receipts. Default: keep history.
--confirmSkip the interactive prompt.
Unlinking does not uninstall the GitHub App from the org. To fully remove access, uninstall in GitHub’s Settings → Integrations → Roboticks → Configure → Uninstall.

​
Bulk reattachment after a repo move

When a repo is renamed or transferred between GitHub orgs, the App may need re-linking: 
# Old: acme/warehouse → New: acme-robotics/warehouse
rbtk github unlink --repo acme/warehouse --confirm
rbtk github link --repo acme-robotics/warehouse
Webhook history is preserved unless you pass --purge-history.

​
Webhook secret rotation

Webhook signing secrets rotate automatically every 90 days. Force a rotation now: 
rbtk github rotate-secret --repo acme/warehouse
The new secret is pushed to the GitHub App config; no action required on the GitHub side. Existing in-flight deliveries finish under the old secret.

​
Troubleshooting

rbtk github link --repo acme/warehouse --no-block-merge
link is idempotent — re-running with new flags updates the link in place.

​
Next

GitHub App installation

The App-install flow (web UI).

Test commands

What runs after a PR triggers a Check Run.