Submitting Analyses

Use this page when you have CI output and want RootCoz to turn it into a report. It covers the four input modes, what each one needs, the difference between collecting CI results and running AI analysis over them, and the role you need before you can submit anything.

Prerequisites

• A running RootCoz server. See Quickstart or Deploying Rootcoz.
• An account with the operator or admin role. reviewer and viewer can read results but cannot submit.
• At least one AI provider credential for claude, gemini, or cursor, unless you are only collecting CI results.
• Your input: a Jenkins job and build, a Prow job and build ID, a JUnit XML file, or raw JUnit XML text.

Quick Example

rootcoz analyze --source file --file junit-results.xml

This queues a JUnit XML analysis from the terminal and prints the job ID to poll. The same work from the browser is New Analysis → Upload File → Submit Analysis.

Step-by-Step

1. Open New Analysis.

The form loads your server defaults first, so most fields are already filled in. If the defaults request times out, the form still works and shows a warning that it fell back to local values.

You are signed in as operator or admin; otherwise the New Analysis link is not available and the API returns a permission error.

1. Pick the input mode that matches what you have.

The four mode buttons are Jenkins Job, Prow Job, Paste XML, and Upload File. Upload File and Paste XML are both JUnit XML input and send the same file request type; the difference is only how the XML gets into the form.

Paste XML and Upload File only accept JUnit XML. Console output, log files, and HTML error pages are not parsed as an empty report — they fail the XML parse, and the job ends as failed with a parse error. A job reaches the empty-report path only when the XML is well-formed and contains no failing tests.

1. Fill in only what the mode needs.

Everything outside the mode's own section is optional and falls back to your server settings. The form sends the additional-repository and peer-provider lists only when they are non-empty, so leaving those fields unfilled does not override a configured server default.

Note: Jenkins and Prow validate what you type before the request is sent. An invalid Prow job name or a non-numeric build ID is rejected client-side; GCS Prefix is also checked against the job name and build ID server-side when you fill it in.

1. Click Submit Analysis.

The button stays disabled until the mode's required fields are valid and an AI provider and model are available — with one exception. If a Tests Repo URL is filled and both AI fields are left empty, the form defers the AI choice to the repository's own .rootcoz/settings.json and enables the button. Paste XML and Upload File go straight to the report page; Jenkins Job and Prow Job open the status page first because they have to reach your CI server and wait for the build.

See Tracking Analysis Progress for what the status page shows.

1. Know what runs after the request is accepted.

POST /analyze returns 202 immediately with a job_id and does the real work in the background. In order:

Two consequences worth knowing before you submit. A run with fifty failing tests that share three distinct errors makes three AI calls, not fifty. And if every group fails, the job is marked failed rather than quietly reporting partial results.

Note: Analysis sessions run with a restricted tool set (read, ls, find, grep). The AI can read the cloned workspace but cannot run shell commands.

1. Check the result.

The report groups failures by the same error signature used during analysis, so a card can cover several tests. See Reviewing and Classifying Failures for the review and classification workflow, and Exploring History and Reports to find an older run.

Advanced Usage

• Collect results now, analyze later. POST /submit runs the exact same fetch and storage as POST /analyze and then stops before the clone and AI stages. The job is stored with analysis_state=submitted and the summary CI results have been collected and stored. AI analysis has not run. Later, POST /results/{job_id}/analyze runs the AI pipeline in place against the same job ID. Use this when you want a cheap, immediate record of a build and only need the expensive analysis for the ones that matter.

In the web UI, a submitted job shows Submitted in the dashboard Mode column and an Analyze button in the report header instead of Re-Analyze.

Tip: Jobs that predate this split are stored as analyzed, so you never have to guess what a missing analysis_state means.

• Change the analysis context for one run. Tests Repo URL and Ref / Branch, Additional Repositories, Raw Prompt, Peer Analysis, Jira Integration, and AI Call Timeout are all per-submission overrides that take precedence over server settings. See Configuring Analysis Context for details.

• Submit from the terminal. rootcoz analyze and rootcoz submit take the same flags, and --source selects between jenkins, file, and prow. The CLI reads the same server for defaults, so anything you set in the form is set in your CLI profile. Use submit when you want the results stored without running AI.

bash rootcoz analyze --source jenkins --job-name folder/job-name --build-number 123 rootcoz submit --source jenkins --job-name folder/job-name --build-number 123

See CLI Command Reference for the full flag list and Automating Common Tasks with the CLI for scripted workflows.

• Reuse a stored submission. Re-Analyze in the report header replays the original request with your overrides applied and produces a new job ID. Sensitive fields such as the tests repo token are stored encrypted and restored automatically, so you do not re-enter credentials. The new report links back to its origin.

Troubleshooting

• I do not see New Analysis, or the API returns a permission error.
  Your account is viewer or reviewer. Submitting requires operator or admin. Set DEFAULT_USER_ROLE=operator for a local trial, or ask an admin to change your role.

• The form says Select an available AI provider and model.
  No provider the form lists is usable for this account. Add your own API key in your account settings, ask an admin to configure server providers, or use POST /submit and run the AI later with POST /results/{job_id}/analyze.

• Submit Analysis is greyed out.
  The required fields for the selected mode are not filled in. Jenkins needs both Job Name and a positive Build Number; Prow needs a valid Job Name and a numeric Build ID; the XML modes need non-empty XML content.

• A Jenkins or Prow submission fails immediately.
  The server could not reach CI. Check Jenkins URL, Jenkins User, and Jenkins Password / Token, or Prow URL and GCS Bucket, either in the form or in the server environment variables.

• The Prow job fails to find artifacts.
  Leave GCS Prefix empty so RootCoz resolves it, and confirm the GCS Bucket actually holds the build. Source-level problems such as denied GCS access are shown under Source Warnings on the status page rather than failing the run outright.

• The report has no failures but the XML was not empty.
  RootCoz only analyzes failure and error test cases in JUnit XML. Verify you uploaded JUnit XML and not console output, and check the report header's passed and skipped counts.

• The job is completed with No test failures found in the provided input.
  The fetch succeeded and there was nothing to analyze, so RootCoz skipped the AI, the clone, and the workspace entirely. Test outcomes are still saved and the counts still appear on the dashboard.

Related Pages

• Quickstart
• Tracking Analysis Progress
• Reviewing and Classifying Failures
• Configuring Analysis Context
• CLI Command Reference
• API Reference