Help Center/Automation & CI/CD/Quality gates & traceability

Link CI Test Results to a Build or Release

Optionally link CI results to a TestCollab build or release for version, environment, commit, and pipeline traceability.

On this page

Linking an automated test run to a build answers a practical release question: exactly which version, commit, environment, and pipeline run produced these results? TestCollab stores that relationship on the test plan, so every result uploaded to the plan stays connected to the version under test.

Build and release linking is optional. The standard reporting path remains tc createTestPlan, then your test runner, then tc report. Add the build-related options on this page only when that extra traceability is useful.

There are two optional variants: record a build before creating the curated plan, or use tc report --auto-create as an alternative shortcut that creates and links both records.

  • A build records a version and can also record environment, pipeline URL, commit, repository links, and notes.
  • A release groups builds according to your release planning and version patterns.
  • A test plan can link to a build, a release, or both.
  • Automated results are uploaded to the test plan. They inherit the plan's traceability rather than creating a separate build-level test run.

For the TestCollab UI concepts, see Understanding Builds and Releases and The Build Detail Page.

Use this variant when your team curates CI cases with a tag and also wants each fresh plan linked to a build. tc createBuild is not required for result uploads. 

export TESTCOLLAB_TOKEN="your-token"

tc createBuild \
  --project 123 \
  --version "2.14.0" \
  --environment "Staging" \
  --deployment-url "https://ci.example.com/runs/987" \
  --commit "8c51704" \
  --commit-url "https://git.example.com/acme/app/commit/8c51704" \
  --repo-url "https://git.example.com/acme/app" \
  --notes "Nightly regression candidate"

tc createBuild reuses a build with the same version instead of creating a duplicate. An existing build is not overwritten by later flags. If its metadata needs to change, edit the build in TestCollab.

If the build already exists in TestCollab and you know its ID or version, skip this command and pass that value directly to tc createTestPlan --build.

On success, the command writes the resolved ID to tmp/tc_build:

source tmp/tc_build
echo "$TESTCOLLAB_BUILD_ID"
source tmp/tc_build

tc createTestPlan \
  --project 123 \
  --ci-tag-id 88 \
  --assignee-id 17 \
  --build "$TESTCOLLAB_BUILD_ID"

--build accepts either a build ID or a version. Using the ID written by tc createBuild avoids ambiguity when older project data contains duplicate versions. The build must already exist for createTestPlan; this command does not create a missing build.

Keep the normal case mapping in your test names, such as [TC-42] Checkout succeeds. Build linking adds traceability but does not change how tc report matches results to TestCollab cases. 

source tmp/tc_test_plan

# Your normal test runner creates the result file
pytest --junitxml=results.xml

tc report \
  --project 123 \
  --test-plan-id "$TESTCOLLAB_TEST_PLAN_ID" \
  --format junit \
  --result-file ./results.xml

The report command updates the linked plan. Do not add --build here: tc report --build is only valid with --auto-create. Reporting to an existing plan keeps the build and release already assigned to that plan.

Add --release to tc createTestPlan when you know the numeric TestCollab release ID: 

tc createTestPlan \
  --project 123 \
  --ci-tag-id 88 \
  --assignee-id 17 \
  --build 902 \
  --release 77

--release accepts a positive release ID, not a release name or version. The CLI does not create releases. Create and configure the release in TestCollab first. See Using Releases with Build Tracking.

A build can also be matched to an existing release by the release's version rules on the TestCollab server. When an auto-created plan is linked to that build, the plan can pick up the build's release. Check the resulting build and plan in TestCollab rather than assuming an unmatched version created a release.

For a zero-setup import, --auto-create replaces the normal createTestPlan step. Add --build when this shortcut should also link a build: 

tc report \
  --project 123 \
  --auto-create \
  --format junit \
  --result-file ./results.xml \
  --build "2.14.0" \
  --environment "Staging"

The CLI resolves --build as an ID first when it contains only digits, then as a version. If no build has that version, auto-create mode creates one. It creates a new plan linked to the resolved build and writes the plan ID to tmp/tc_test_plan.

--environment only applies when --build creates a new build. It does not update an existing build, and it cannot be used without --build. For the complete resource and matching behavior, see Zero-Setup CI Reporting.

Do not run both createTestPlan and report --auto-create for the same upload. They are alternative plan-creation paths.

If you opt into tc createBuild, the CLI recognizes six CI environments and fills fields that you did not pass explicitly. Explicit flags always win.

Provider Fields detected when available
Azure DevOps Version, commit, repository URL, commit URL, pipeline URL
GitHub Actions Version, commit, repository URL, commit URL, workflow run URL
GitLab CI Version, commit, repository URL, commit URL, pipeline URL
Bitbucket Pipelines Version, commit, repository URL, commit URL, pipeline URL
CircleCI Version, commit, build URL
Jenkins Version, commit, build URL

Environment and notes are never inferred. CircleCI and Jenkins clone URLs are not converted into repository or commit web links, so pass --repo-url and --commit-url explicitly when you want them. 

# In a recognized CI job, the provider usually supplies the version and links
tc createBuild --project 123 --environment "Staging"

Outside a recognized CI environment, --version is required. There is no --branch option; use --notes if branch context must be recorded.

After the pipeline finishes, open the build to review its version and provenance, then follow its linked test plans. Open the plan to review the automated results and any manual execution in the same release context. This lets a team compare results by build without inferring the tested version from a plan title or CI log.

For an EU-hosted account, add this option to each TestCollab command that your chosen path actually runs: 

--api-url https://api-eu.testcollab.io

The command did not find a build number in a recognized CI environment. Pass your pipeline's stable build or release version explicitly with --version.

The version already exists, so the build is reused as-is. Review the warning and edit that build in TestCollab if its environment, links, commit, or notes are wrong.

--build on tc report requires --auto-create. For an existing plan, link the build when creating or editing the plan, then report with only --test-plan-id.

Use a numeric build ID. createTestPlan and auto-create reporting cannot safely choose between duplicate version records.

Confirm an existing release's version rules match the build version, or pass that release's numeric ID to tc createTestPlan --release. Neither createBuild nor report creates a release.

Last updated 2026-08-26.