Setting up CI/CD and Automated Tests for Hybrid Quantum‑Classical Applications — Workflow, Checklist, and Pipeline Templates
CI/CDTestingDevOpsHybrid QuantumPipeline TemplatesQiskitPennyLane

Setting up CI/CD and Automated Tests for Hybrid Quantum‑Classical Applications — Workflow, Checklist, and Pipeline Templates

CCoQubit Editorial Team
2026-11-11
8 min read

Build safer hybrid quantum CI/CD with simulator tests, hardware smoke tests, tolerance rules, cost estimates, and reusable pipeline templates.

A reliable hybrid quantum-classical application needs more than a working circuit: it needs repeatable tests, controlled backend access, and clear rules for deciding whether a result is acceptable. This guide presents a practical CI/CD workflow, reusable pipeline templates for GitHub Actions, GitLab CI, and Azure DevOps, and a simple estimation method for simulator time, hardware usage, queue exposure, and failure risk.

Overview

Hybrid applications divide work between ordinary software and a quantum execution layer. A classical process may prepare data, bind circuit parameters, submit jobs, collect measurements, and update an optimizer. The quantum portion may run on a local simulator, a managed simulator, or physical hardware. Each boundary introduces a testing concern.

A useful quantum CI/CD pipeline separates these concerns into four stages:

  1. Static checks: format code, run type checks, inspect dependencies, and validate configuration.
  2. Fast simulator tests: verify circuit construction, parameter binding, result parsing, and classical control flow without using a cloud backend.
  3. Integration and regression tests: execute representative workloads against a chosen simulator and compare stable metrics with stored baselines.
  4. Hardware smoke tests: run a small, deliberately bounded circuit on an approved device or provider endpoint, usually on a schedule or after an explicit deployment approval.

Do not make every pull request wait for hardware. Queue time, provider authentication, backend availability, shot limits, and changing calibration conditions make physical execution a poor default for fast feedback. Treat hardware as a controlled validation environment, while local simulators provide the main development loop.

For circuit-level planning, record qubit count, depth, two-qubit gates, shots, and expected runtime before execution. The quantum circuit resource estimation guide provides a useful companion process.

How to estimate

Estimate pipeline exposure with a small worksheet rather than a single headline number. For each test class, record:

  • Runs per pipeline: the number of circuits, parameter combinations, and repetitions.
  • Shots per circuit: the measurement count used for each execution.
  • Execution target: local simulator, remote simulator, or hardware backend.
  • Expected duration: circuit execution time plus compilation, upload, queue, and result retrieval time.
  • Retry policy: whether a transient failure can be retried and how many times.
  • Budget unit: provider task, circuit, shot, runtime minute, or an internal budget token. Use the unit supplied by the selected provider or your internal accounting system rather than assuming that all platforms bill identically.

A simple planning formula is:

execution volume = circuits × parameter sets × shots × retries

This is an execution estimate, not a universal pricing formula. A provider may count work differently, and a simulator may be constrained by memory rather than shots. For a hardware smoke test, estimate the upper bound before enabling the job:

maximum exposure = tests × circuits per test × shots per circuit × allowed retries

Then attach guardrails: a maximum number of circuits, a maximum shot count, a maximum retry count, an allowed backend list, and a failure action. If any limit is exceeded, fail before submission.

For result quality, compare distributions or expectation values using tolerances rather than exact equality. Exact counts are often unsuitable because sampling introduces variation and hardware introduces noise. Define the metric, tolerance, and test conditions together. For example, a test might require an expectation value to remain within an agreed absolute tolerance, or require selected probabilities to stay within a tolerance while allowing unimportant low-probability states to vary.

Keep separate thresholds for simulator regression and hardware smoke tests. A deterministic or tightly controlled simulator can use a stricter threshold. A hardware test should document its noise model, shot count, mitigation settings if any, and acceptable range. The guide to interpreting quantum measurement results can help standardize the comparison layer.

Inputs and assumptions

Before writing YAML, make the application reproducible outside CI. Pin the Python version and important SDK dependencies, preserve a lockfile or constraints file, and expose backend configuration through environment variables. Never commit provider credentials, account identifiers that should remain private, or production budget settings to the repository.

A practical repository layout might look like this:

project/
  src/
    quantum_app/
  tests/
    unit/
    integration/
    hardware/
  pyproject.toml
  requirements-ci.txt
  requirements-hardware.txt
  .github/workflows/ci.yml
  .gitlab-ci.yml
  azure-pipelines.yml

Use test markers so the pipeline can choose the appropriate scope. For example, tests can be grouped as unit, integration, and hardware. The exact test runner is a project choice; the important point is that a normal pull request must not accidentally discover and submit hardware jobs.

Store a small reference dataset and baseline results with an explicit schema. A baseline should identify the SDK version, simulator or backend name, circuit revision, shot count, random seed where supported, and comparison metric. When any of those inputs changes, treat the baseline as potentially invalid rather than silently replacing it.

GitHub Actions template

name: quantum-ci

on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '0 3 * * 1'

jobs:
  simulator:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: python -m pip install --upgrade pip
      - run: pip install -r requirements-ci.txt
      - run: python -m pytest tests/unit tests/integration -m 'not hardware'

  hardware-smoke:
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    environment: quantum-hardware
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -r requirements-hardware.txt
      - run: python -m pytest tests/hardware -m hardware
        env:
          QUANTUM_BACKEND: ${{ vars.QUANTUM_BACKEND }}
          QUANTUM_TOKEN: ${{ secrets.QUANTUM_TOKEN }}
          MAX_SHOTS: ${{ vars.MAX_SHOTS }}

The action versions and runner images should be reviewed periodically. Replace them according to your organization's change-control process rather than copying them indefinitely.

GitLab CI template

stages:
  - test
  - hardware

simulator-tests:
  stage: test
  image: python:3.11-slim
  script:
    - pip install -r requirements-ci.txt
    - python -m pytest tests/unit tests/integration -m 'not hardware'

hardware-smoke:
  stage: hardware
  image: python:3.11-slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - when: manual
  script:
    - pip install -r requirements-hardware.txt
    - python -m pytest tests/hardware -m hardware
  variables:
    QUANTUM_BACKEND: $QUANTUM_BACKEND
    MAX_SHOTS: $MAX_SHOTS

Azure DevOps template

trigger:
- main

pool:
  vmImage: ubuntu-latest

stages:
- stage: SimulatorTests
  jobs:
  - job: Test
    steps:
    - task: UsePythonVersion@0
      inputs:
        versionSpec: '3.11'
    - script: |
        python -m pip install --upgrade pip
        pip install -r requirements-ci.txt
        python -m pytest tests/unit tests/integration -m "not hardware"
      displayName: Run simulator tests

- stage: HardwareSmoke
  dependsOn: SimulatorTests
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
  jobs:
  - job: Smoke
    steps:
    - task: UsePythonVersion@0
      inputs:
        versionSpec: '3.11'
    - script: |
        pip install -r requirements-hardware.txt
        python -m pytest tests/hardware -m hardware
      env:
        QUANTUM_BACKEND: $(QUANTUM_BACKEND)
        QUANTUM_TOKEN: $(QUANTUM_TOKEN)
        MAX_SHOTS: $(MAX_SHOTS)
      displayName: Run hardware smoke test

These templates are intentionally provider-neutral. Adapt the installation files, authentication method, backend selection, and submission command to the SDK in use, whether the project uses Qiskit, Cirq, PennyLane, Amazon Braket, or another framework. Consult the relevant SDK documentation after version upgrades because imports, backend discovery, job APIs, and configuration options can change.

Worked examples

Example 1: pull-request simulator test

Assume a pull request runs 12 unit circuits and 4 integration circuits. Each integration circuit is evaluated for 3 parameter sets, with 256 shots per set. The simulator stage therefore evaluates 12 unit circuits plus 12 parameterized integration executions. If the suite runs only once and has no retry, the integration execution volume is:

4 circuits × 3 parameter sets × 256 shots = 3,072 shots

This number helps size runtime and identify accidental growth. It does not represent a provider charge when the work is local. If a change increases parameter sets from 3 to 30, the pipeline may still pass functionally while becoming too slow for ordinary pull requests. Add a test-volume limit or move the larger sweep to a scheduled regression job. Parameter-sweep design is covered in the parameter sweep guide.

Example 2: scheduled hardware smoke test

Assume the smoke suite contains 2 small circuits, each configured for 128 shots, with one retry permitted only for a classified transient submission failure. The maximum planned exposure is:

2 circuits × 128 shots × 2 attempts = 512 shots

Before submission, the test should verify that the selected backend is on an allowlist, the requested shot count is below the configured limit, credentials are present, and the circuit meets a maximum depth or gate-count rule. If the first attempt succeeds, the retry allowance is not consumed. If the provider reports a queue or availability condition, decide whether to fail, skip, or reschedule; make that behavior visible in the pipeline rather than hiding it as a passing test.

Compare the returned result with a broad, documented tolerance. Store the raw result as a build artifact when permitted, alongside metadata needed to interpret it. Do not overwrite the expected baseline automatically after a noisy result. A human review or controlled baseline-update command is safer.

Testing checklist

  • Unit tests validate circuit construction, parameter binding, serialization, and result parsing.
  • Integration tests validate the complete classical-to-quantum-to-classical loop on a simulator.
  • Regression tests compare distributions, expectation values, objective values, or other meaningful metrics.
  • Noise tests exercise readout, gate, and decoherence assumptions where they affect application behavior. See the quantum noise models guide.
  • Hardware smoke tests use small circuits, explicit backend allowlists, bounded shots, and controlled credentials.
  • Every hardware test records SDK version, backend, circuit revision, shots, timestamp, and comparison tolerance.
  • Failures distinguish code defects from authentication errors, queue delays, provider errors, and tolerance breaches.
  • Pipeline logs exclude secrets and contain enough identifiers to trace a job without exposing sensitive information.

When to recalculate

Recalculate execution volume, runtime expectations, tolerances, and budget exposure whenever the circuit, shot count, parameter sweep, retry policy, or backend changes. A transpilation change can alter depth and two-qubit operations even when the high-level algorithm appears unchanged. Review those effects before enabling a new hardware target; the transpilation guide provides a useful checklist.

Refresh pipeline definitions after major SDK, provider API, test-runner, container-image, or CI-platform changes. Also revisit them when authentication methods, backend identifiers, queue behavior, execution limits, or pricing inputs change. A quarterly review of runner images and dependency locks is a practical baseline, with an additional review for each major SDK release.

Before merging a pipeline change, run this short operational check:

  1. Run the complete simulator suite locally or in an isolated CI branch.
  2. Calculate the new maximum execution volume using the formula above.
  3. Confirm that tolerance rules match the metric and noise conditions.
  4. Verify that hardware credentials are unavailable to ordinary pull requests.
  5. Run one manually approved smoke test against the intended backend.
  6. Record the SDK, runner, backend, and baseline versions in the change description.

With this separation of fast simulator feedback, measured regression coverage, and deliberately limited hardware validation, hybrid quantum applications can use familiar software delivery practices without pretending that quantum execution behaves like an ordinary deterministic unit test.

Related Topics

#CI/CD#Testing#DevOps#Hybrid Quantum#Pipeline Templates#Qiskit#PennyLane
C

CoQubit Editorial Team

Quantum Software Development Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.