Skip to content

Quickstart

This walkthrough takes you from your invitation to a first triaged signature in about fifteen minutes. You'll sign in, pick a project, upload one small regression with the dvforge CLI, watch it arrive, and then set the status and owner of one of its signatures.

Before you start, you need:

  • An invitation to DV Forge. Sign-in is by invitation; your organization's admin arranges it.
  • The dvforge CLI, from your DV Forge contact. It ships as a Python package, or as a standalone binary for RHEL, Rocky or Alma 8 and 9.
  • A JUnit XML file from a regression run, and the simulation logs it refers to. The example below gives you a minimal pair if you'd rather start small.
  • The triager role or higher to change a signature's status and assignee (step 10). With a lower role you can still follow every other step.

Steps

  1. Sign in. Open https://app.daruur.cloud and sign in with the account from your invitation.

    Expected: the Dashboard opens, with the sidebar on the left.

  2. Select your project. At the top of the sidebar, open the project switcher and choose your team's project. Entries read org-slug / Project name.

    Expected: list pages such as Failures and Signatures now show that project. The app remembers your choice in this browser.

    Note

    Your first sign-in also creates a personal organization with a project named default. If the switcher shows only that project, you haven't been added to your team's organization yet. Ask your organization's admin.

  3. Get a project API token. Ask a project admin for a token for your project with the ingest:write scope. Projects, roles and tokens shows them how.

    Expected: you receive a secret that starts with dvf_. It's shown only once, so keep it in your CI secret store or password manager.

  4. Point the CLI at DV Forge. Set the API address and the token as environment variables. Prefer the variable to the --token flag: flags show up in process lists.

    export DVFORGE_URL=https://api.daruur.cloud
    export DVFORGE_TOKEN='dvf_…'      # the token from step 3
    dvforge --version
    

    Expected: dvforge --version prints the CLI version.

    Projects that use a data plane

    If your project sends results through a data plane, set DVFORGE_URL to the data plane's address instead. Your admin knows it. Uploading straight to DV Forge fails with this project ingests through its data plane.

  5. Prepare a JUnit file and a log. Use your own regression output, or create this minimal example: one passing test and one failing test, with the failing test's log.

    results.xml
    <testsuites>
      <testsuite name="nightly">
        <testcase name="fifo_overflow" classname="fifo">
          <properties><property name="seed" value="1234"/></properties>
        </testcase>
        <testcase name="axi_burst" classname="axi">
          <properties><property name="seed" value="77"/></properties>
          <failure message="scoreboard mismatch"/>
        </testcase>
      </testsuite>
    </testsuites>
    
    out/axi_burst_77.log
    UVM_INFO @ 0: reporter [RNTST] Running test axi_burst...
    UVM_ERROR /proj/tb/axi_scoreboard.sv(212) @ 48210: uvm_test_top.env.sb [SB_MISMATCH] expected 0x1f got 0x0f
    UVM_FATAL @ 48210: reporter [TIMEOUT] Watchdog expired
    

    The CLI attaches a log to a test when the log's file name contains the test name (and, better, the seed), or when the JUnit names the log file. See The dvforge CLI for the matching rules.

  6. Check the upload with a dry run. --dry-run shows what would be sent without touching the network.

    dvforge upload --dry-run \
      --name "quickstart 1" --external-id quickstart-1 --branch main \
      --junit results.xml --logs 'out/**/*.log'
    

    Expected: output that starts with dry run: nothing will be sent and ends with a line like would send 2 jobs in 1 batch(es) (pass 1, fail 1); 1 logs to upload.

  7. Upload the regression. Run the same command without --dry-run.

    dvforge upload \
      --name "quickstart 1" --external-id quickstart-1 --branch main \
      --junit results.xml --logs 'out/**/*.log'
    

    Expected: a summary like this, and exit code 0:

    regression 6f0c2a4e-… (created): quickstart 1 [quickstart-1]
    jobs sent: 2 in 1 batch(es) - pass 1, fail 1
    logs: 1 uploaded (1 new, 0 already stored)
    status: complete
    

    --external-id identifies the regression. Rerunning the same command updates the same regression instead of creating a second one, and resumes an interrupted upload. If the command fails, Troubleshooting and FAQ explains each exit code.

  8. Watch the regression arrive. In the app, select Failures and reload the page. Your regression is at the top of the list. Open it.

    Expected: the regression page shows the job count, pass rate, failing jobs and the signatures they fell into. While the regression is live (still receiving uploads), this page updates on its own as jobs are processed. When the upload completes, the badge changes to complete. Select log next to a failing job to read its log.

    Tip

    To watch a long upload fill in live, open the regression page while your CI is still uploading. Processing continues for a moment after the CLI exits; add --wait to make the CLI wait until every batch is processed.

  9. Open the signature. Select Signatures in the sidebar, or select a signature in the regression's Signatures table.

    Expected: the signature page opens. Its header shows the signature key, the bucketing version and the status badge Untriaged. Below are the Triage panel, hit counts, the discussion, the history of regressions it hit, and its recent failures.

  10. Triage it. In the Triage panel:

    • Open Move to… next to the status and choose Investigating.
    • Under Assignee, select Assign to me, or pick a teammate from the list.

    Expected: the status badge changes to Investigating, the panel reads "Changed just now by you", and both changes appear in the Activity timeline. The assignee starts watching the signature. Someone you assign gets a notification under the bell at the top of the sidebar.

    If Move to… is grayed out, hover over it: "Triager role required to change status" means your role is below triager. See Permissions.

What's next