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

> Reference for rbtk github commands — link a repo to a Roboticks project, check link status, unlink.

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

<Info>
  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](/github-app/installation) for the install flow.
</Info>

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

```bash theme={null}
rbtk github link --repo acme/warehouse
rbtk github link --repo acme/warehouse --branch main --watch-prs all
```

| Flag                               | Description                                                                                    |
| ---------------------------------- | ---------------------------------------------------------------------------------------------- |
| `--repo <owner/name>`              | GitHub repo (required)                                                                         |
| `--branch <ref>`                   | Default branch for release evidence (auto-detected if omitted)                                 |
| `--watch-prs all\|labeled\|none`   | Which PRs trigger Check Runs. `labeled` waits for a `roboticks` label. Default: `all`.         |
| `--block-merge / --no-block-merge` | Whether the Roboticks Check Run is required for merge. Default: `--no-block-merge` (advisory). |

### Examples

```bash theme={null}
# 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.

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
rbtk github unlink --repo acme/warehouse
```

| Flag                  | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| `--repo <owner/name>` | GitHub repo (required)                                                         |
| `--purge-history`     | Also delete historical Check Runs and webhook receipts. Default: keep history. |
| `--confirm`           | Skip the interactive prompt.                                                   |

<Warning>
  Unlinking does not uninstall the GitHub App from the org. To fully remove access, uninstall in GitHub's **Settings → Integrations → Roboticks → Configure → Uninstall**.
</Warning>

## Bulk reattachment after a repo move

When a repo is renamed or transferred between GitHub orgs, the App may need re-linking:

```bash theme={null}
# 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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="link returns `App not installed`">
    Install the App on the repo (or its parent org) via [GitHub App → Installation](/github-app/installation), then retry `rbtk github link`.
  </Accordion>

  <Accordion title="Check Runs never appear after link">
    Run `rbtk github status --repo <repo>`. If `LAST WEBHOOK` is older than a few minutes after a push, the webhook isn't reaching us — check **Settings → Webhooks** on the GitHub repo for delivery errors.
  </Accordion>

  <Accordion title="Block-merge accidentally enabled">
    ```bash theme={null}
    rbtk github link --repo acme/warehouse --no-block-merge
    ```

    `link` is idempotent — re-running with new flags updates the link in place.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="GitHub App installation" icon="github" href="/github-app/installation">
    The App-install flow (web UI).
  </Card>

  <Card title="Test commands" icon="flask-vial" href="/cli/test-commands">
    What runs after a PR triggers a Check Run.
  </Card>
</CardGroup>