Skip to main content

Quickstart

By the end of this page you will have:
  1. The Roboticks GitHub App installed on a repo.
  2. One requirement uploaded.
  3. One pytest test marked @confirms("REQ-001").
  4. A passing GitHub Check Run with a coverage delta.
Budget: 10 minutes if you have a repo and a working pytest environment.

Step 1: Install the GitHub App

  1. Sign in at app.roboticks.io.
  2. Click Settings → Integrations → GitHub App → Install.
  3. Choose the repo (or whole org); accept the permissions (Contents: read, Checks: write, PRs: write, Metadata: read).
  4. Back in Roboticks, link the installation to a project.
You should see the repo appear under Settings → Repositories with status Connected.
See GitHub App → Installation for the full permissions list and webhook events.

Step 2: Upload your first requirement

The fastest path is inline YAML. Create roboticks/requirements.yaml at the repo root:
Push it. The GitHub App detects the file and ingests one requirement.
For real projects, upload a ReqIF export from Polarion/Jama or a PDF of the standard you derive from. See Requirements → Upload.

Step 3: Install the SDK

This installs the roboticks package and registers a pytest plugin. The plugin reads @confirms(...) decorators and emits them into JUnit XML in a format the platform parses into traceability links.
The plugin is loaded automatically by pytest’s entry-point mechanism. No conftest.py edits required.

Step 4: Annotate a test

Run it locally:
The test passes. Locally, nothing else changed. The magic shows up on push.

Step 5: Open a PR

Within ~30 seconds, GitHub posts a Roboticks Check Run:
Done. Your repo now has a closed traceability loop — requirement → confirming test → passing result → Check Run.

What just happened

Where to go next

Upload real requirements

ReqIF round-trip, PDF→LLM extraction, structured authoring.

See the traceability matrix

Requirement × test heatmap with gap and regression filters.

Write more tests

Assertion helpers, fault injection, MCAP capture.

Self-host the runner

Bring your own compute. Free for self-hosted.

Generate an evidence pack

Per-release PDF + ReqIF + ZIP, tamper-evident, audit-ready.

Map a standard

See how ISO 10218 or EU MR 2023/1230 derive into your project.

Troubleshooting

  • Confirm the GitHub App is installed on the repo: Settings → Integrations → GitHub App in the Roboticks dashboard.
  • Check Webhook deliveries for HTTP 2xx responses. A 4xx usually means the webhook secret rotated; reinstall the App.
  • See GitHub App → Troubleshooting.
  • Verify pip install roboticks is in your test environment (pip show roboticks).
  • Run pytest with -p roboticks.pytest_plugin -v to confirm the plugin loaded.
  • Inspect the JUnit XML for <property name="roboticks.confirms" value="REQ-001"/>.
  • YAML must validate against requirement.schema.json.
  • Required fields: id, title, text, type.
  • Check roboticks/ is at the repo root, not a subdirectory.