Bitbucket Pipelines integration

API testing in Bitbucket Pipelines

A first-party Docker image and Bitbucket Pipe for Total Shift Left. Run test packs on every pull request, gate merges on pass-rate thresholds, and publish JUnit and JSON artifacts.

Book DemoAll integrations

What this integration gives you

The Shift-Left API integration runs as a Docker container or as a Bitbucket Pipe inside your Bitbucket Pipelines pipeline. It connects to your Shift-Left API deployment, triggers a test pack, polls until completion, applies a quality gate, and emits JUnit XML and JSON artifacts. Use it to gate pull requests, run scheduled regression suites, or chain into release pipelines on Bitbucket Cloud.

  • Pipe + Docker support

    Use the Bitbucket Pipe shorthand or run the Docker image directly — both forms documented and supported.

  • Workspace variable scoping

    Share credentials across repos via Workspace variables; per-repo overrides via Repository variables.

  • Branch protection ready

    The step exits non-zero on quality-gate failure, integrating cleanly with "Require successful builds" merge checks.

  • Self-hosted runner support

    Run on Bitbucket cloud runners or your own self-hosted runners for air-gapped Shift-Left deployments.

bitbucket-pipelines.yml example

Drop this into your bitbucket-pipelines.yml. Runs on every pull request and on main-branch merges. Two equivalent forms shown — pick the one that matches your pipeline conventions.

image: atlassian/default-image:4

pipelines:
  pull-requests:
    '**':
      - step:
          name: Shift-Left API Tests
          script:
            - docker run --rm \
                -e SHIFTLEFT_URL="$SHIFTLEFT_URL" \
                -e SHIFTLEFT_EMAIL="$SHIFTLEFT_EMAIL" \
                -e SHIFTLEFT_PASSWORD="$SHIFTLEFT_PASSWORD" \
                -e SHIFTLEFT_TEST_PACK_ID="$SHIFTLEFT_TEST_PACK_ID" \
                -e PASS_THRESHOLD="95" \
                -e FAIL_ON_ERROR_TESTS="true" \
                -v $(pwd):/workspace \
                totalshiftleft/shift-left-api-runner:latest
          artifacts:
            - api-results.xml
            - api-summary.json
          services:
            - docker

  branches:
    main:
      - step:
          name: Shift-Left API Tests (main)
          script:
            - pipe: docker://totalshiftleft/shift-left-api-pipe:latest
              variables:
                SHIFTLEFT_URL: $SHIFTLEFT_URL
                SHIFTLEFT_EMAIL: $SHIFTLEFT_EMAIL
                SHIFTLEFT_PASSWORD: $SHIFTLEFT_PASSWORD
                SHIFTLEFT_TEST_PACK_ID: $SHIFTLEFT_TEST_PACK_ID
                PASS_THRESHOLD: "95"
                FAIL_ON_ERROR_TESTS: "true"

Pipeline variables

Define these in Bitbucket Repository settings → Pipelines → Repository variables (per repo) or Workspace settings → Pipelines → Workspace variables (across many repos). Mark credential values as Secured to mask them in build logs.

VariableDescription
SHIFTLEFT_URLBase URL of your Shift-Left API deployment. Define as a Repository, Deployment, or Workspace variable depending on scope.
SHIFTLEFT_EMAIL / SHIFTLEFT_PASSWORDAuthentication credentials. Always mark as Secured so values are masked in logs.
SHIFTLEFT_TEST_PACK_IDID of the test pack. Repository-scoped variable typically.
PASS_THRESHOLDMinimum pass-rate percentage for the quality gate.
FAIL_ON_ERROR_TESTSBoolean. If true, ERROR test results fail the step regardless of pass-rate.

Bitbucket Pipelines integration — FAQ

Contact us at

support@totalshiftleft.com

to learn more

  • Does this work with Bitbucket Data Center / self-managed Bitbucket?
    The pipe and Docker image are designed for Bitbucket Cloud Pipelines. For Bitbucket Data Center / self-managed deployments, the equivalent CI is Bamboo or third-party runners — talk to us about supported approaches and we'll match the integration shape to your environment.
  • How do I store credentials in Bitbucket?
    Use Bitbucket repository, deployment, or workspace variables with the Secured flag enabled. Secured variables are masked in logs and not exposed to forked pull requests by default. For credentials shared across many repos, use Workspace variables.
  • How do I gate pull requests on test results?
    The pipe exits non-zero when the pass-rate threshold or ERROR-test policy fails. Combine with Bitbucket's "Require successful builds" merge check (Repository settings → Branch permissions → Merge checks) to block merging on API test failures.
  • Why are there two example forms (docker run + pipe)?
    Both work. The docker run form is most explicit and works on any Bitbucket Pipelines image with Docker available. The pipe form (pipe: docker://...) is a Bitbucket-native shorthand that handles variable injection cleanly. Pick whichever fits your existing pipeline conventions.
  • How do I run multiple test packs in parallel?
    Use parallel steps inside a Bitbucket Pipelines stage. Each parallel step is independent and runs on its own runner. Note that each parallel step consumes a build minute — Bitbucket Pipelines bills by build-minutes, so heavy parallelism trades cost for wall-clock time.
  • Can the pipe run on a self-hosted runner?
    Yes. Bitbucket Pipelines supports self-hosted runners. Configure your runner inside the same network as your self-hosted Shift-Left API deployment, then reference the runner in the runs-on key of your pipeline step.

More CI/CD integrations

Add API testing to your Bitbucket pipelines

Forever-free Citizen Developer or 15-day Enterprise trial. Drop a step into bitbucket-pipelines.yml and you're testing on the next push.

Book DemoSee pricing