CI/CD Integration

Trigger TraceLoom test runs directly from your CI pipeline using an API key. The most common pattern is a post-deploy smoke run — tests fire automatically after a successful production deployment.

Authentication

Generate an API key in Settings → API Keys. Store it as a secret in your CI provider — never commit it to source control.

All requests to POST /api/runs require an Authorization header:

Authorization: Bearer tlk_your_api_key_here

GitHub Actions — Post-Deploy Trigger

The recommended pattern is a separate workflow that fires after your deploy workflow succeeds. This keeps deployment and testing concerns cleanly separated.

Add TRACELOOM_API_KEY as a GitHub Actions secret, then create .github/workflows/trigger-traceloom-run.yml:

name: Trigger TraceLoom Run

on:
  workflow_dispatch:  # allows manual trigger from the Actions tab
  workflow_run:
    workflows: ["Deploy to Production"]  # name of your deploy workflow
    types: [completed]

jobs:
  trigger-run:
    runs-on: ubuntu-latest
    if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'

    steps:
      - name: Trigger TraceLoom test run
        env:
          COMMIT_SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
          BRANCH: ${{ github.event.workflow_run.head_branch || github.ref_name }}
        run: |
          curl -f -X POST https://<your-api-url>/api/runs \
            -H "Authorization: Bearer ${{ secrets.TRACELOOM_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "{
              \"name\": \"Post-deploy: ${BRANCH} @ ${COMMIT_SHA}\",
              \"triggerSource\": \"api\",
              \"commitSha\": \"${COMMIT_SHA}\",
              \"testSource\": {
                \"type\": \"git\",
                \"gitRepo\": \"https://github.com/${{ github.repository }}.git\",
                \"gitBranch\": \"main\"
              },
              \"testPattern\": \"tests/**/*.spec.ts\",
              \"serverCount\": 5,
              \"timeout\": 300
            }"

Replace <your-api-url> with your TraceLoom API URL (found in Settings). The workflow triggers automatically when your deploy workflow completes successfully, or you can run it manually from the Actions tab at any time.

Request Body Reference

Field	Type	Required	Description
`testSource`	object	Yes	Git repo + branch, or S3 URI containing your test files
`testPattern`	string	Yes	Glob pattern for test file discovery (e.g. `tests/*/.spec.ts`)
`serverCount`	number	No	Number of EC2 Spot instances to launch (default: 1)
`timeout`	number	No	Per-shard timeout in seconds (default: 600, max: 3600)
`name`	string	No	Human-readable label for the run in the dashboard
`commitSha`	string	No	Git commit SHA — stored on the run for traceability
`triggerSource`	string	No	`api`, `schedule`, or `manual`

Git vs S3 Test Source

TraceLoom can pull your test files from a GitHub repository or an S3 bucket:

# Git source (uses your connected GitHub OAuth token)
"testSource": {
  "type": "git",
  "gitRepo": "https://github.com/your-org/your-repo.git",
  "gitBranch": "main"
}

# S3 source (zip of your test files)
"testSource": {
  "type": "s3",
  "bucket": "your-bucket",
  "key": "tests/suite.zip"
}

Next Steps

API Keys — create and manage API keys
Schedules — run tests on a cron schedule without CI
Test Runs — view results, traces, and run history

Last updated: May 2026