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:
- Static checks: format code, run type checks, inspect dependencies, and validate configuration.
- Fast simulator tests: verify circuit construction, parameter binding, result parsing, and classical control flow without using a cloud backend.
- Integration and regression tests: execute representative workloads against a chosen simulator and compare stable metrics with stored baselines.
- 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:
- Run the complete simulator suite locally or in an isolated CI branch.
- Calculate the new maximum execution volume using the formula above.
- Confirm that tolerance rules match the metric and noise conditions.
- Verify that hardware credentials are unavailable to ordinary pull requests.
- Run one manually approved smoke test against the intended backend.
- 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.