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.

​
GitHub App Troubleshooting

Most GitHub App issues fall into four buckets: webhooks failing, Check Runs not posting, the installation in an unexpected state, or token / rate-limit problems. Work through this page in order — each section has a fast diagnostic and a fix.
The fastest universal diagnostic: Roboticks dashboard → Settings → Integrations → GitHub App → Webhook log. It shows every delivery, its HTTP response, and the downstream job. If you can’t see a delivery for an action you just took, the issue is between GitHub and us; if you can see it but the job didn’t run, the issue is downstream.

​
Webhook returns 4xx

​
Symptom

In GitHub: Settings → Applications → Roboticks → Advanced → Recent Deliveries shows deliveries with red 401 / 403 / 422 status codes.

​
Diagnosis

StatusLikely cause
401 UnauthorizedHMAC verification failed — our copy of the webhook secret no longer matches yours.
403 ForbiddenThe installation was deleted or the repo was removed from it.
422 Unprocessable EntityPayload schema we don’t recognise — usually an event we never subscribed to that GitHub is delivering anyway.
5xxA transient platform issue on our side. GitHub will retry 8 times over ~8 hours.

​
Fix

  1. Roboticks dashboard → Settings → Integrations → GitHub App → click Rotate webhook secret. Rotation is atomic — old deliveries in flight fail, new deliveries verify with the new secret.
  2. GitHub re-signs subsequent webhooks with the new secret automatically; no manual step on the GitHub side.
  3. Click Redeliver on the failed events in the GitHub delivery view to replay them.
  1. Confirm the App is still installed in GitHub → Settings → Applications → Installed GitHub Apps.
  2. Confirm the repo is in scope: Roboticks → Configure → Repository access.
  3. If the install or repo is gone, re-install per Installation — historical data is retained.
Safe to ignore. We acknowledge with 422 to make GitHub stop retrying an event we don’t handle. If the same event repeats and you want it handled, open a ticket — it’s probably a new GitHub event we should add to the subscription list.
Check status.roboticks.io. If no incident is posted and the failures persist for >5 minutes, file a ticket; include the X-GitHub-Delivery UUID from a failed delivery so we can find it in our trace store.

​
Check Run never posts

​
Symptom

A PR is opened, but no Roboticks check appears in the Checks tab — not even queued.

​
Diagnosis

Walk these four checks in order:
1

Is the App installed on this repo?

GitHub → repo → Settings → Branches (or any settings page) → scroll to the App badge in the sidebar. If Roboticks isn’t there, install per Installation.
2

Is the installation suspended?

GitHub → Settings → Applications → Installed GitHub Apps → Roboticks. A red Suspended badge means the org admin paused the App. Click Unsuspend. Suspended installs receive no webhooks until unsuspended.
3

Is the repo linked to a Roboticks project?

Roboticks dashboard → Settings → Repositories. If the repo shows Connected but not linked, click Link to project. Webhooks for an unlinked repo are acknowledged but skipped (visible in the webhook log with reason no_project).
4

Did the PR match the project's policy?

Default policy skips drafts and forks. Settings → Project → Check Run policy toggles these. Drafts that were marked ready-for-review will trigger a run on the ready_for_review event.
If all four pass and the Check Run still doesn’t post: the dashboard Run log will show the job and the failure reason. If it shows nothing at all, file a ticket with the PR URL and we’ll trace it.

​
Check Run posted, but conclusion = action_required

This is by design when a human-in-the-loop step is pending. The most common cases:
  • Requirements PDF awaiting review — go to Requirements → Pending review in the dashboard, accept or edit the LLM-extracted requirements, and the next push will re-evaluate.
  • Standards subscription update — a pinned standard published an amendment that touches requirements in this PR. Review the diff at Standards → Updates.
action_required does not block merge unless your branch protection lists Roboticks as required.

​
Check Run posted, but conclusion = neutral on every PR

This usually means the test job ran but no JUnit XML was found, or no @confirms(...) decorators were detected.

​
Fix

  1. In the dashboard Run log, open the latest run → Artifacts tab. If the JUnit file is missing or empty, your test command isn’t emitting JUnit — see Writing tests.
  2. If JUnit is present but no requirements are linked, run pytest -p roboticks.pytest_plugin -v locally and confirm the plugin loads. The plugin is auto-registered when roboticks is installed, but if a wrapper script overrides the Python environment it may be skipped.

​
Rate limit exceeded

​
Symptom

The webhook log shows successful deliveries, but jobs sit in queued for minutes or the dashboard shows GitHub API: 403 rate limit exceeded.

​
Diagnosis

GitHub Apps have a per-installation rate budget that scales with the number of repositories. Three causes:
CauseFix
Burst — many PRs opened at onceWait. The budget refills hourly. Jobs queue and dispatch as budget returns; no Check Runs are lost.
Long-running script polling GET /pullsMove it onto webhooks. Polling is the #1 cause of installation rate exhaustion.
Many Re-run all jobs clicksEach one issues a fresh check-runs POST + log uploads. Avoid scripting it.
We monitor headroom per installation and warn at 75% / page at 95% — you’ll see a banner in the dashboard before a hard failure.

​
Token expiry

You should never see a token-expiry error in normal operation. If you do: 
GitHub API: 401 Bad credentials (installation token expired)
It means the backend’s installation-token cache is stale — usually after a multi-region failover. The fix is automatic: the backend re-mints a token on the next call and retries the failed request once. You’ll see a short blip in the run timeline but the job completes. If you see this error persistently (>5 minutes), file a ticket immediately — it indicates the App private key is unreachable.

​
Repo was renamed or transferred

GitHub fires repository.renamed / repository.transferred events. We update the project ↔ repo mapping automatically — no manual step. The first push or PR after the rename will run cleanly.
Transfers across GitHub accounts (e.g. from a personal account to an org) are treated as an uninstall on the old account and a fresh install on the new one. The App must be re-installed on the destination account and the repo re-linked to the project.

​
Still stuck

Status page

Live incident status.

Open a ticket

Include the X-GitHub-Delivery UUID and PR URL for fastest triage.

Webhooks reference

Re-read the event handling rules.

Check Run reference

Conclusion semantics and re-run paths.