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: 
- id: REQ-001
  title: E-stop halts motion within 100 ms
  type: safety
  asil_pl: PLd
  text: |
    On assertion of the E-stop input, all actuators must reach
    a safe stop state within 100 ms, as measured at the wheel encoders.
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

pip install roboticks
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

# tests/test_estop.py
import time
from roboticks import confirms, deadline

@confirms("REQ-001")
@deadline(milliseconds=100)
def test_estop_halts_motion(robot):
    robot.command_velocity(1.0)
    t0 = time.monotonic()
    robot.assert_estop()
    robot.wait_until_stopped()
    assert (time.monotonic() - t0) * 1000 < 100
Run it locally: 
pytest tests/test_estop.py
The test passes. Locally, nothing else changed. The magic shows up on push.

​
Step 5: Open a PR

git checkout -b first-traced-pr
git add roboticks/requirements.yaml tests/test_estop.py
git commit -m "Add E-stop deadline test"
git push origin first-traced-pr
gh pr create --fill
Within ~30 seconds, GitHub posts a Roboticks Check Run: 
✓ Roboticks · 1/1 requirements confirmed · 1 test, 1 pass
  REQ-001  confirmed by tests/test_estop.py::test_estop_halts_motion
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.