CircleCI integration

API testing in CircleCI

A first-party CLI for Total Shift Left. Drop into any CircleCI job, gate workflows on pass-rate thresholds, and render JUnit reports natively in the CircleCI Tests tab.

Book DemoAll integrations

What this integration gives you

The Shift-Left API CLI installs from npm and runs as a single step inside any CircleCI job. It connects to your Shift-Left API deployment, triggers a test pack, polls until completion, applies a quality gate, and writes JUnit XML and JSON artifacts that CircleCI parses natively. Use it to gate workflows on API quality, run scheduled regression runs, or chain into broader release pipelines.

  • Native test reporting

    CircleCI parses JUnit and shows test summaries in the Tests tab — including failures, timings, and trends across builds.

  • Context-secure credentials

    Use CircleCI Contexts to scope credentials to specific workflows. No project-level secrets to manage and rotate.

  • Self-hosted runner support

    Works with CircleCI cloud or your self-hosted runners — useful when your Shift-Left deployment is behind a firewall.

  • Parallel-friendly

    Run shards via CircleCI parallelism or independent jobs in the same workflow.

.circleci/config.yml example

Drop this into your .circleci/config.yml. References a Context for credentials, runs on main and release branches, applies a 95% pass-rate gate, and stores JUnit results for the CircleCI Tests tab.

version: 2.1

jobs:
  api-tests:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run:
          name: Install Shift-Left runner
          command: npm install -g @totalshiftleft/runner
      - run:
          name: Run API test pack
          command: |
            shift-left-runner run \
              --server-url "$SHIFTLEFT_URL" \
              --email "$SHIFTLEFT_EMAIL" \
              --password "$SHIFTLEFT_PASSWORD" \
              --test-pack-id "$SHIFTLEFT_TEST_PACK_ID" \
              --pass-threshold 95 \
              --fail-on-error-tests true \
              --junit-output api-results.xml \
              --json-output api-summary.json
      - store_test_results:
          path: api-results.xml
      - store_artifacts:
          path: api-results.xml
      - store_artifacts:
          path: api-summary.json

workflows:
  test:
    jobs:
      - api-tests:
          context: shift-left-credentials
          filters:
            branches:
              only:
                - main
                - /^release\/.*/

Environment variables

Define these in a CircleCI Context (Organization Settings → Contexts) and reference the context from your workflow. Contexts give you central rotation, audit trail, and team-level access controls.

VariableDescription
SHIFTLEFT_URLBase URL of your Shift-Left API deployment. Define in a CircleCI Context for secure sharing across projects.
SHIFTLEFT_EMAIL / SHIFTLEFT_PASSWORDAuthentication credentials. Always use a CircleCI Context (org-scoped) — never project environment variables for credentials.
SHIFTLEFT_TEST_PACK_IDID of the test pack. Define per-project; reference from the workflow.

CircleCI integration — FAQ

Contact us at

support@totalshiftleft.com

to learn more

  • Does this work with self-hosted Shift-Left API?
    Yes. The CLI calls the public /api/v1 endpoints, so any reachable Shift-Left deployment works. For self-hosted deployments behind a firewall, run the job on a CircleCI self-hosted runner inside the same network as the Shift-Left API.
  • How should I store credentials in CircleCI?
    Use a CircleCI Context (Organization Settings → Contexts) to scope credentials to the workflows that need them. Reference the context in your workflow definition with the context: key. Avoid project-level environment variables for credentials — they are easier to misuse and harder to rotate.
  • How do CircleCI test results show in the UI?
    Use store_test_results with the JUnit XML path. CircleCI parses JUnit and renders test summaries in the Tests tab on each job, including timing, failures, and stack traces. Combine with store_artifacts to keep the JSON summary for deeper analysis.
  • Is there an official CircleCI orb?
    A reusable orb wrapping the CLI is on the roadmap and will simplify the setup further. The current CLI-based approach works on any CircleCI image with Node.js available and is forward-compatible with the orb when it ships.
  • How do I gate workflows on test results?
    The CLI exits non-zero when the pass-rate threshold or ERROR-test policy fails, which fails the job. Combine with workflow approval gates or branch protection in your VCS to block downstream jobs (deploys, releases) on API test failures.
  • Can I run multiple test packs in parallel?
    Yes. Use CircleCI parallelism with separate test-pack-IDs per shard, or define multiple jobs in the same workflow. CircleCI bills by minutes, so heavy parallelism trades cost for wall-clock time.

More CI/CD integrations

Add API testing to your CircleCI workflows

Forever-free Citizen Developer or 15-day Enterprise trial. The CLI installs from npm in one line.

Book DemoSee pricing