GitHub Actions integration

API testing in GitHub Actions

A first-party GitHub Action for Total Shift Left. Trigger test packs on every pull request, gate merges on pass-rate thresholds, and publish JUnit / JSON artifacts — without writing custom workflow code.

Book DemoAll integrations

What this integration gives you

The Shift-Left API GitHub Action runs test packs as part of any GitHub Actions workflow. It connects to your Shift-Left API deployment via the public REST API, triggers a run, polls until completion, applies a quality gate, and emits JUnit XML and JSON artifacts to the runner workspace. Use it to gate PR merges on API quality, run scheduled regression suites against staging environments, or chain API tests into broader release pipelines.

  • Quality gates on PRs

    Pass-rate thresholds and ERROR-test policies — any failure exits non-zero and blocks the merge via branch protection.

  • JUnit + JSON artifacts

    Native test-reporter compatibility with the dorny/test-reporter action and any tool that consumes JUnit XML.

  • Self-hosted runner support

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

  • Matrix-friendly

    Run multiple test packs in parallel via a matrix strategy. Each invocation is independent.

Workflow example

Drop this into .github/workflows/api-tests.yml. Stores credentials as GitHub Secrets, runs on every PR and main-branch push, applies a 95% pass-rate gate, and publishes a JUnit report.

name: API Tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Shift-Left API Test Pack
        uses: Total-Shift-Left/shift-left-api-action@v1
        with:
          server-url: ${{ secrets.SHIFTLEFT_URL }}
          email: ${{ secrets.SHIFTLEFT_EMAIL }}
          password: ${{ secrets.SHIFTLEFT_PASSWORD }}
          test-pack-id: ${{ vars.SHIFTLEFT_TEST_PACK_ID }}
          pass-threshold: 95
          fail-on-error-tests: true
          junit-output: api-results.xml
          json-output: api-summary.json

      - name: Upload Test Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-results
          path: |
            api-results.xml
            api-summary.json

      - name: Publish JUnit Report
        if: always()
        uses: dorny/test-reporter@v1
        with:
          name: API Tests
          path: api-results.xml
          reporter: java-junit

Action inputs

All inputs are passed via the with: block. Required inputs must be set; optional inputs have sensible defaults documented below.

InputTypeDescription
server-urlstring · requiredBase URL of your Shift-Left API deployment (e.g. https://app.totalshiftleft.ai). No trailing slash.
email / passwordstring · requiredAuthentication credentials. Store both as encrypted GitHub Secrets — never inline.
test-pack-idstring · requiredID of the test pack to execute. Pull from a repo / org variable to keep workflows portable.
pass-thresholdinteger · default 0Minimum pass-rate percentage. Use 0 to disable threshold checking; 95 is a common starting point for PR gates.
fail-on-error-testsboolean · default trueFail the workflow step if any test reports ERROR (regardless of pass-rate threshold).
poll-intervalinteger · default 10Seconds between status polls while waiting for the run to complete.
timeoutinteger · default 60Maximum minutes to wait before timing out the step.
junit-outputstring · optionalWorkspace-relative path for JUnit XML output. Pair with dorny/test-reporter or actions/upload-artifact for visibility.
json-outputstring · optionalWorkspace-relative path for the JSON run summary.

Quality gates that actually fail builds

The point of CI/CD-integrated API testing isn't reporting — it's blocking. Two independent gate types:

  • Pass-rate threshold

    Set pass-threshold: 95 to require 95% of tests to pass. Run results below the threshold exit non-zero. Combine with GitHub branch protection rules requiring this check to pass before merge.

  • ERROR-test policy

    Set fail-on-error-tests: true to fail the step on any test reporting ERROR (test infrastructure failure, network failure, auth failure) regardless of pass-rate. Useful for catching test-environment regressions, not just API regressions.

For deployment topology — including how the action reaches a self-hosted Shift-Left API behind a firewall — see the deployment page.

GitHub Actions integration — FAQ

Contact us at

support@totalshiftleft.com

to learn more

  • Where do I store the Shift-Left API credentials in GitHub?
    Store SHIFTLEFT_URL, SHIFTLEFT_EMAIL, and SHIFTLEFT_PASSWORD as encrypted GitHub Secrets at the repository or organization level. Never commit credentials to the workflow YAML. For self-hosted Shift-Left deployments, the SHIFTLEFT_URL secret should point at your internal hostname (private runners may be required to reach it).
  • Does the action work with self-hosted Shift-Left deployments?
    Yes. The action calls the public /api/v1 endpoints, so any reachable Shift-Left deployment — multi-tenant SaaS or self-hosted on your infrastructure — works. For self-hosted deployments behind a firewall, run the action on a self-hosted GitHub runner inside the same network, or expose the Shift-Left API to GitHub-hosted runners through your standard egress controls.
  • How do quality gates fail the build?
    Two independent checks: pass-threshold (minimum pass-rate percentage) and fail-on-error-tests (any ERROR result fails the step). Either failing causes the action step to exit non-zero, which fails the job and — through GitHub branch protection rules — can block the PR from merging.
  • Can I run multiple test packs in parallel?
    Yes. Use a matrix strategy in your workflow with one matrix entry per test-pack-id. Each matrix run is independent, parallelism is bounded by your runner pool, and results from each can be uploaded as separate artifacts.
  • Does the action support pull-request comment summaries?
    The action emits JUnit XML and JSON artifacts. Pair with dorny/test-reporter or a custom comment action to post a summary on the PR. We also publish a reusable workflow that combines the action with PR commenting — see the GitHub repository for the latest reference.
  • What's the relationship between this action and the public REST API?
    The action is a thin convenience wrapper around the same /api/v1 endpoints anyone can call directly. If you need behavior the action doesn't support, you can call the REST API directly from any GitHub Actions step using curl or your preferred HTTP client.

More CI/CD integrations

Add Shift-Left API to your next pull request

Forever-free Citizen Developer or 15-day Enterprise trial. The GitHub Action installs in two lines of YAML.

Book DemoSee pricing