Creating Builds from Your CI/CD Pipeline

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 \   
--version BUILD_VERSION \   
--environment ENVIRONMENT_NAME \   
[other optional flags]

Required Parameters

--project - your TestCollab project ID (number)
--version - the software version, e.g., v2.14.1 or build-2024-03-15

Optional Parameters

Parameter	What It Does	Example
`--environment`	Environment where deployed	`Production`, `Staging`
`--commit`	Git commit hash	`abc123def456`
`--commit-url`	Links to commit	`https://dev.azure.com/org1/proj1/_git/repo1/commit/dcf8d40435298cb6dd5a72ac1d81fb9`
`--branch`	Git branch name	`main`, `release/2.14`
`--deployment-url`	Link to the deployment	`https://deployments.company.com/12345`
`repo-url`	Link to the repo	`https://dev.azure.com/org1/proj1/_git/repo1`
`--notes`	Description of changes	`"Fixed login bug, added analytics"`
`--api-key`	Your TestCollab API key (or use env var `TESTCOLLAB_API_KEY`)
`--api-url`	Your TestCollab API URL (defaults to production)

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 created: ID 42 (version: v2.14.1)

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_API_KEY: $(TESTCOLLAB_API_KEY)  # Set as a pipeline variable
  inputs:
    targetType: 'inline'
    script: |
      tc createBuild \
        --project 45 \
        --version "v$(Build.BuildNumber)" \
        --environment "Production" \
        --commit "$(Build.SourceVersion)" \
        --branch "$(Build.SourceBranchName)" \
        --deployment-url "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)" \
        --notes "Deployed to Production"

      # Store the build ID for later steps
      cat tmp/tc_build >> $GITHUB_ENV

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_API_KEY: ${{ secrets.TESTCOLLAB_API_KEY }}
  run: |
    tc createBuild \
      --project 45 \
      --version "v${{ github.run_number }}" \
      --environment "Production" \
      --commit "${{ github.sha }}" \
      --branch "${{ github.ref_name }}" \
      --deployment-url "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
      --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 \
        --version "v${CI_PIPELINE_ID}" \
        --environment "Production" \
        --commit "$CI_COMMIT_SHA" \
        --branch "$CI_COMMIT_BRANCH" \
        --deployment-url "$CI_PIPELINE_URL" \
        --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 deployed
tc 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_API_KEY: $(TESTCOLLAB_API_KEY)
            inputs:
              targetType: 'inline'
              script: |
                tc createBuild \
                  --project 45 \
                  --version "v$(Build.BuildNumber)" \
                  --environment "Production" \
                  --commit "$(Build.SourceVersion)" \
                  --branch "$(Build.SourceBranchName)" \
                  --deployment-url "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"

                # Save build ID for later steps
                cat tmp/tc_build >> $GITHUB_ENV

          # 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_API_KEY: $(TESTCOLLAB_API_KEY)
            inputs:
              targetType: 'inline'
              script: |
                # Run your tests and generate a report file
                npm test > results.json

                # Upload the results to the test plan
                tc report \
                  --project 45 \
                  --test-plan-id $TEST_PLAN_ID \
                  --format mochawesome \
                  --result-file results.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.

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 report command)