Why Use the CLI?
Manually creating a build requires someone to open TestCollab and fill out a form.
Using the CLI means:
Builds are recorded automatically every time you deploy
The build includes deployment details from your pipeline (commit hash, branch, build number)
Your TestCollab Deployment card shows full traceability from code to testing
Subsequent pipeline steps can reference the build to link test results to it
No manual work required
Prerequisites
You need:
TestCollab API key - generate this in your TestCollab profile settings
Project ID - found in your project's settings
TestCollab CLI installed
The tc createBuild Command
The basic command is:
tc createBuild --project PROJECT_ID --environment ENVIRONMENT_NAME
The CLI reads the version, commit, commit URL, repository URL and deployment URL from your CI provider's own environment. It detects Azure DevOps, GitHub Actions, GitLab CI, Bitbucket Pipelines, CircleCI and Jenkins, and logs which provider it matched. Pass a flag only to override what it detected.
Required Parameters
--project- your TestCollab project ID (number)
Optional Parameters
Parameter | What It Does | Example |
| Version that was built or deployed. Defaults to the CI build number |
|
| Environment where deployed |
|
| Git commit hash. Defaults to the CI commit |
|
| Links to commit. Defaults to the CI commit URL |
|
| Link to the pipeline run. Defaults to the CI run URL |
|
| Link to the repo. Defaults to the CI repository |
|
| Description of changes |
|
| Your TestCollab API key (or use env var |
|
| Your TestCollab API URL (defaults to production) |
|
There is no --branch flag. Branch is not recorded on a build.
How It Works: Match-Then-Create
The CLI performs these actions:
Search - it asks TestCollab, "Do you already have a build with version
v2.14.1?"Match - if found, it reuses that build and verifies the details
Create - if not found, it creates a new one
This prevents duplicate builds when your pipeline runs multiple times with the same version.
Output and the Build ID File
When successful, the CLI outputs:
Build "v2.14.1" (created, id 42) — Production
✅ Build recorded. Build ID: 42
A build that already exists reports (existing, id 42) instead of (created, id 42).
It also creates a file at tmp/tc_build containing:
TESTCOLLAB_BUILD_ID=42
Subsequent pipeline steps can read this file and use the build ID for linking test plans or test results.
Provider-Specific Examples
Azure DevOps Pipeline YAML
Add this to your pipeline's deployment job:
task: Bash@3
displayName: 'Record build in TestCollab'
env:
TESTCOLLAB_TOKEN: $(TESTCOLLAB_TOKEN) # Set as a pipeline variable
inputs:
targetType: 'inline'
script: |
tc createBuild \
--project 45 \
--environment "Production" \
--notes "Deployed to Production"
# Expose the build ID to later steps (Azure syntax)
BUILD_ID=$(cut -d= -f2 tmp/tc_build)
echo "##vso[task.setvariable variable=TESTCOLLAB_BUILD_ID]$BUILD_ID"
Then, in a later step, reference the build:
- task: Bash@3
displayName: 'Run tests against build'
inputs:
targetType: 'inline'
script: |
source tmp/tc_build
echo "Running tests against build $TESTCOLLAB_BUILD_ID"
# Your test execution command here
GitHub Actions Workflow YAML
Add this to your workflow's deployment job:
- name: Record build in TestCollab
env:
TESTCOLLAB_TOKEN: ${{ secrets.TESTCOLLAB_TOKEN }}
run: |
tc createBuild \
--project 45 \
--environment "Production" \
--notes "Deployed to Production"
cat tmp/tc_build >> $GITHUB_ENV
- name: Run tests against build
run: |
echo "Running tests against build $TESTCOLLAB_BUILD_ID"
# Your test execution command here
GitLab CI YAML
Add this to your .gitlab-ci.yml deployment job:
deploy_production:
stage: deploy
environment:
name: production
script:
- tc createBuild \
--project 45 \
--environment "Production" \
--notes "Deployed to Production"
- cat tmp/tc_build >> build.env
artifacts:
reports:
dotenv: build.env
Then reference it in a later job:
run_tests:
stage: test
needs:
- deploy_production
script:
- echo "Running tests against build $TESTCOLLAB_BUILD_ID"
# Your test execution command here
What You See in TestCollab
After running tc createBuild in your pipeline, the build appears in TestCollab with a Deployment Card on its detail page. Instead of just showing the version and environment, it shows:
Version - the software version
Commit - the Git commit hash; click to view on your repository
Repository - the repository URL; click to visit it
Deployed - the date and time of deployment
Release - the release this build is part of
Environment - the deployment environment
This provides full traceability from your code commit through to test results.
Integration with Test Result Reporting
The tc createBuild command works alongside the existing test result reporting workflow. In a complete testing pipeline, you use both:
tc createBuild— Record the software version being deployedtc report— Upload automated test execution results against that version
This links your test results to a specific software version for full traceability from code to testing to deployment.
Complete Pipeline Example
Here's how both commands work together in an Azure DevOps pipeline:
stages:
- stage: Deploy
displayName: 'Deploy to Production'
jobs:
- job: DeployJob
steps:
# Step 1: Record the build version
- task: Bash@3
displayName: 'Record build in TestCollab'
env:
TESTCOLLAB_TOKEN: $(TESTCOLLAB_TOKEN)
inputs:
targetType: 'inline'
script: |
tc createBuild \
--project 45 \
--environment "Production"
# Save the build ID for later steps
BUILD_ID=$(cut -d= -f2 tmp/tc_build)
echo "##vso[task.setvariable variable=TESTCOLLAB_BUILD_ID]$BUILD_ID"
# Step 2: Deploy (your existing deployment steps here)
- task: Bash@3
displayName: 'Deploy application'
inputs:
targetType: 'inline'
script: |
# Your deployment commands here
echo "Deployed v$(Build.BuildNumber)"
- stage: Test
displayName: 'Run Tests'
dependsOn: Deploy
jobs:
- job: TestJob
steps:
# Step 3: Run automated tests and upload results
- task: Bash@3
displayName: 'Run tests and report results'
env:
TESTCOLLAB_TOKEN: $(TESTCOLLAB_TOKEN)
inputs:
targetType: 'inline'
script: |
# Create a test plan for this build. --build ties the plan to
# the version that was just deployed.
tc createTestPlan \
--project 45 \
--ci-tag-id 12 \
--assignee-id 34 \
--build "$TESTCOLLAB_BUILD_ID"
source tmp/tc_test_plan
# Run your tests. The mochawesome reporter writes its own JSON file.
npx mocha --reporter mochawesome
# Upload the results to that plan. The plan already carries the build,
# so --build is not needed here.
tc report \
--project 45 \
--test-plan-id "$TESTCOLLAB_TEST_PLAN_ID" \
--format mochawesome \
--result-file mochawesome-report/mochawesome.json
For more details on the tc report command and result file formats, see "Uploading Test Results Using TestCollab CLI" in the help documentation.
Next Steps
Once the build is created in TestCollab, you can:
Link test plans to this build to track testing against it
Use the build ID to report test results that are scoped to this deployment
View the build's detail page to see full test results and coverage
See the "Linking Test Plans to a Build" guide for details.
Related Articles
Creating and Managing Builds - Manual build creation for non-CI workflows
The Build Detail Page - View deployment information and coverage for automated builds
Linking Test Plans to a Build - Link test plans to the build your pipeline created
Uploading Test Results Using TestCollab CLI - Report test execution results (uses
tc reportcommand)