nexus-upload

A small command that sends one test-results file to Nexus for Jira from any CI system (GitLab, Azure Pipelines, Bitbucket Pipelines, Jenkins, CircleCI, TeamCity or a shell).

Single file, no dependencies. Node 16+ (it uses fetch when available and falls back to node:https, so it also runs in older images such as postman/newman).

Install

From npm (needs Node 16 or later), no install step at all:

npx @resyncnz/nexus-upload results.xml --project NEX

Or add it to a project, which puts nexus-upload on the path:

npm install --save-dev @resyncnz/nexus-upload
npx nexus-upload results.xml --project NEX

Alternative: download it from nexus.resync.nz/integrations. It is a single file, so you can fetch it in the CI job and run it with Node:

curl -fsSLo nexus-upload.mjs https://nexus.resync.nz/downloads/nexus-upload-0.3.5.mjs
node nexus-upload.mjs results.xml --project NEX

You can also commit nexus-upload.mjs to your repository, or install the package from the same site:

npm install --save-dev https://nexus.resync.nz/downloads/nexus-upload-0.3.5.tgz

Usage

export NEXUS_URL=...      # results URL from Project Settings > Nexus > CI (a CI secret)
export NEXUS_API_KEY=...  # API key with the ingest scope (a CI secret)
nexus-upload results.xml --project NEX --environment staging

| Option | Environment variable | Meaning | |---|---|---| | --url | NEXUS_URL | Results URL (required) | | | NEXUS_API_KEY | API key (required; env var only, never a flag) | | --project | NEXUS_PROJECT | Jira project key (required) | | --format | NEXUS_FORMAT | junit-xml, xunit-xml, robot-xml, nunit-xml, testng-xml, cucumber-json, mocha-json, mochawesome-json, newman-json, playwright-json, json. Detected when omitted | | --environment | NEXUS_ENVIRONMENT | Environment label | | --test-set | NEXUS_TEST_SET | Test Set (cycle) key | | --build | NEXUS_BUILD | Build id. Default: the CI system's build number | | --commit | NEXUS_COMMIT | Commit. Default: the CI system's commit SHA | | --component | NEXUS_COMPONENT | Component label | | --configuration | NEXUS_CONFIGURATION | Test Configuration id | | --system-out comment | NEXUS_SYSTEM_OUT | JUnit only: post each test's own <system-out> as a plain-text comment on its run (off by default; at most 50 per upload, 8,000 characters each) | | --step-matching off | NEXUS_STEP_MATCHING | Record only each case's overall result, as one row, and leave the case's steps untouched (0.3.0; default on, which matches the result to the case's steps) | | --soft | | Warn on failure but exit 0 | | --dry-run | | Show what would be sent; send nothing |

Build and commit are read automatically from GitHub Actions, GitLab, Azure Pipelines, Bitbucket Pipelines, CircleCI and Jenkins variables.

Format detection: .xml files are JUnit XML (root <testsuites>/<testsuite>) or xUnit.net v2 (root <assemblies>); .json files are Cucumber (an array of features), Mocha (stats + tests), Playwright (config + suites), Postman/Newman (run.executions, from newman run -r json) or Nexus JSON (results). Anything else asks for --format.

Exit codes: 0 sent (or --soft), 1 Nexus refused it or could not be reached, 2 usage or file problem. Nexus answers 202 with {"status":"accepted"} only after it has processed every result of the upload (SEC27-H9, 28/09/2026: nothing is left running in the background behind an "accepted"); the per-test outcome is in the delivery log on the CI page. A {"status":"partial"} answer means Nexus holds the upload and what it recorded so far and finishes the rest itself; the CLI sends it again to continue or confirm. Still "partial" after 8 sends exits 1 with "not confirmed finished": check the delivery log before sending again.

Idempotency-Key (0.3.3, 28/09/2026): --idempotency-key <key> (or NEXUS_IDEMPOTENCY_KEY), 16-128 of A-Z a-z 0-9 . _ : -, is sent on every send of the upload. Nexus then treats any later send with the same key and file as the same delivery, never as a new run, however late it arrives. Not sent unless you set it; in CI the detected build number already keeps a resend of the same file the same upload.

The key is never printed, nor is the URL path (only the host). The same upload is sent again until Nexus has recorded all of it: after a 202 whose body says "partial" (the time limit reached part-way), a 500, a 502/503/504 or a network error, up to 8 sends with a pause growing from 2 s to 15 s. Nexus remembers what each upload already recorded, so a resend never records a result twice (0.2.0, 27/09/2026).

Large reports (0.3.7, 11/10/2026): a report of more than 500 results, or over 5 MB, is split into parts of at most 500 results (and under 5 MB), each in the report's own format, and sent one after another to the same project, test set, build and environment. JUnit XML is cut by <testcase> (each case stays inside a copy of its own <testsuite>, with its name and attributes), and xUnit.net, NUnit, TestNG and Robot by their result element; Playwright JSON by test (retries stay together); Cucumber JSON by scenario (with its Background, inside its feature; the rows of one Scenario Outline stay together); Mocha JSON, mochawesome and the Nexus JSON format by test. Each part is its own delivery, so sending the whole file again re-sends identical parts and Nexus ignores what it already recorded; with --idempotency-key, part n of N sends <key>:pnofN. Parts are sent at least 0.7 s apart (under Nexus's 120 requests a minute), a 413 on a part waits 30 s and sends it again, a 429 waits its Retry-After. The log shows "part 3 of 10: 500 results accepted" and one summary at the end (parts accepted, results sent, failed parts); if a part fails the others are still sent and the exit code is 1, except after a 400, 401 or 403 (bad request, key or inactive licence), which stops the run. Per-result matched/unmatched/skipped counts are in the delivery log (Project Settings > CI), one entry per part. A Postman/Newman report cannot be split safely: over 500 distinct requests it is refused before anything is sent, with the count, the limit and the fix (split the run, or use JUnit output). --count <file> prints how many results a file holds (an upper bound of what Nexus counts, since Nexus counts only results with an Automation Key). A file over 100 MB is not read. Bad report (0.3.7): a 400 now shows its real reason first; "a Nexus older than 28/09/2026" is mentioned only when Nexus accepts the plain file after refusing the envelope.

One huge result (0.3.8, 12/10/2026): a single test with a multi-MB output or failure text no longer makes the whole upload fail. That result's system-out, system-err and failure/error text keep their first and last 100,000 characters with a plain-words marker in between, a warning is printed on stderr, and everything else is sent as it was.

Replay protection (0.3.2, 28/09/2026): every send carries X-Nexus-Timestamp (Unix seconds) and a fresh random X-Nexus-Nonce, new for each send including a resend. Nexus refuses a nonce it has already seen from the same key and a timestamp more than 5 minutes from its own clock (a 400, not resent; check the machine's clock).

Develop

node --test      # from this folder; uses a local fake Nexus, no network

Licence

MIT. © 2026 Resync Consulting Limited. See LICENSE.