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

# Quickstart - First Traced PR in 10 Minutes

> Install the GitHub App, upload requirements, annotate a test with @confirms, and see the traceability matrix update on your first PR.

# 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](https://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.

<Check>
  You should see the repo appear under **Settings → Repositories** with status **Connected**.
</Check>

See [GitHub App → Installation](/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:

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

<Tip>
  For real projects, upload a ReqIF export from Polarion/Jama or a PDF of the standard you derive from. See [Requirements → Upload](/requirements/upload).
</Tip>

## Step 3: Install the SDK

```bash theme={null}
pip install roboticks
```

This installs the [`roboticks`](https://pypi.org/project/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.

<Info>
  The plugin is loaded automatically by pytest's entry-point mechanism. No `conftest.py` edits required.
</Info>

## Step 4: Annotate a test

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

```bash theme={null}
pytest tests/test_estop.py
```

The test passes. Locally, nothing else changed. The magic shows up on push.

## Step 5: Open a PR

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

<Check>
  **Done.** Your repo now has a closed traceability loop — requirement → confirming test → passing result → Check Run.
</Check>

## What just happened

```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
sequenceDiagram
    participant Dev
    participant GH as GitHub
    participant App as Roboticks GitHub App
    participant Run as Runner
    participant Plat as Platform
    Dev->>GH: git push (PR)
    GH->>App: pull_request webhook
    App->>Plat: enqueue test job
    Plat->>Run: dispatch (hosted Fargate)
    Run->>Run: pytest with roboticks plugin
    Run->>Plat: JUnit + @confirms metadata
    Plat->>Plat: link REQ-001 → test
    Plat->>GH: Check Run (coverage delta)
    GH->>Dev: ✓ Roboticks passing
```

## Where to go next

<CardGroup cols={2}>
  <Card title="Upload real requirements" icon="file-import" href="/requirements/upload">
    ReqIF round-trip, PDF→LLM extraction, structured authoring.
  </Card>

  <Card title="See the traceability matrix" icon="table-cells" href="/traceability/matrix">
    Requirement × test heatmap with gap and regression filters.
  </Card>

  <Card title="Write more tests" icon="flask-vial" href="/testing/writing-tests-pytest">
    Assertion helpers, fault injection, MCAP capture.
  </Card>

  <Card title="Self-host the runner" icon="microchip" href="/runners/installation">
    Bring your own compute. Free for self-hosted.
  </Card>

  <Card title="Generate an evidence pack" icon="file-shield" href="/evidence/generation">
    Per-release PDF + ReqIF + ZIP, tamper-evident, audit-ready.
  </Card>

  <Card title="Map a standard" icon="scale-balanced" href="/standards/overview">
    See how ISO 10218 or EU MR 2023/1230 derive into your project.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The GitHub Check Run never appears">
    * 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](/github-app/troubleshooting).
  </Accordion>

  <Accordion title="The test ran but no requirement was linked">
    * 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"/>`.
  </Accordion>

  <Accordion title="Requirement upload failed">
    * YAML must validate against [`requirement.schema.json`](https://github.com/roboticks-io/roboticks-sdk/blob/main/schemas/requirement.schema.json).
    * Required fields: `id`, `title`, `text`, `type`.
    * Check `roboticks/` is at the repo root, not a subdirectory.
  </Accordion>
</AccordionGroup>