Bitbucket Integration Pipe | Usetrace Help Center

This pipe simply clones and executes the Universal Integration and forwards all supported parameters.

Reference: Usetrace/universal-integration

1. Enable Bitbucket Pipelines
In your Bitbucket repository:

Go to Repository settings > Pipelines.
Click Enable Pipelines if it's not already enabled.

This will create a bitbucket-pipelines.yml file at the root of your repository.

2. Add the Usetrace Integration Pipe to Your Pipeline

Run a Single Trace

pipelines:
  branches:
    development:
      - step:
          name: Run Single Usetrace Trace
          image: atlassian/default-image:latest
          script:
            - pipe: docker://public.ecr.aws/usetrace/bitbucket-integration:latest
              variables:
                TRACE_ID: 'your-trace-id-here'
                BROWSERS: 'chrome,firefox'
                BUILD_TIMEOUT_SECONDS: '3600'
                FAIL_ON_FAILED_TRACES: 'true'

Run an Entire Project

pipelines:
  branches:
    development:
      - step:
          name: Run Usetrace Project
          image: atlassian/default-image:latest
          script:
            - pipe: docker://public.ecr.aws/usetrace/bitbucket-integration:latest
              variables:
                PROJECT_ID: 'your-project-id-here'
                TAGS: 'smoke,critical'
                COMMIT: '${BITBUCKET_COMMIT}'
                COMMIT_LINK: 'https://bitbucket.org/${BITBUCKET_REPO_FULL_NAME}/commits/${BITBUCKET_COMMIT}'
                BROWSERS: 'chrome'

Webhook + Custom Parameters

pipelines:
  branches:
    development:
      - step:
          name: Run Usetrace with Webhook and Parameters
          image: atlassian/default-image:latest
          script:
            - pipe: docker://public.ecr.aws/usetrace/bitbucket-integration:latest
              variables:
                TRACE_ID: 'your-trace-id-here'
                USETRACE_API_KEY: '${USETRACE_API_KEY}'
                WEBHOOK_URL: 'https://your.webhook/endpoint'
                WEBHOOK_WHEN: 'changes'
                WEBHOOK_SECRETKEY: '${WEBHOOK_SECRET}'
                WEBHOOK_USERNAME: '${WEBHOOK_USER}'
                WEBHOOK_PASSWORD: '${WEBHOOK_PASS}'
                PARAMETERS: '"env":"staging","featureFlag":"on"'

3. Add Required Variables to Repository Settings
Go to Repository Settings > Pipelines > Repository variables, and add the following if used:

Name	Description
`USETRACE_API_KEY`	Your Usetrace API key (optional unless required by your setup)
`WEBHOOK_SECRET`	(Optional) HMAC secret for webhook
`WEBHOOK_USER`	(Optional) Webhook basic auth username
`WEBHOOK_PASS`	(Optional) Webhook basic auth password

Parameters Overview

One of TRACE_ID or PROJECT_ID is required.

Variable	Required	Default	Description
`TRACE_ID`	One-of	–	ID of a single trace to run
`PROJECT_ID`	One-of	–	ID of a project to run all included traces
`BROWSERS`	Optional	chrome	Comma-separated list of browsers
`BASE_URL`	Optional	–	Overrides default base URL
`PARAMETERS`	Optional	–	Custom parameters in JSON format
`USETRACE_API_KEY`	Optional	–	API key if needed for authentication
`BUILD_TIMEOUT_SECONDS`	Optional	3600	Max time to wait
`FAIL_ON_FAILED_TRACES`	Optional	true	Fail pipeline if any trace fails
`WEBHOOK_URL`	Optional	–	Result callback URL
`WEBHOOK_WHEN`	Optional	always	Trigger on: `always`, `fails`, or `changes`
`WEBHOOK_SECRETKEY`	Optional	–	HMAC secret
`WEBHOOK_USERNAME`	Optional	–	Webhook basic auth username
`WEBHOOK_PASSWORD`	Optional	–	Webhook basic auth password
`TAGS`	Optional	–	Tags to filter project traces
`COMMIT`	Optional	–	Commit hash
`COMMIT_LINK`	Optional	–	Commit link
`DEBUG`	Optional	false	Enable debug logging

Output

Generates an output.json artifact containing execution results.
If execution fails early, the pipeline step will fail.
If successful but no output is generated, a minimal output.json will be created.

Troubleshooting Tips

Set DEBUG: "true" for verbose shell logs
Ensure network access to GitHub and Usetrace APIs
Increase BUILD_TIMEOUT_SECONDS for longer builds

Local Development

docker build -t usetrace-integration .
docker run --rm \
  -e TRACE_ID="test-trace-id" \
  -e BROWSERS="chrome" \
  -e DEBUG="true" \
  usetrace-integration

References

Universal Integration: Usetrace/universal-integration
Bitbucket Pipelines Docs: Get started with Pipelines
Usetrace API & CI Docs: docs.usetrace.com