CI/CD for Quantum Programs

Quantum CI/CD is not classical CI/CD with a QPU step pasted at the end. A quantum pipeline must validate code, circuits, target compatibility, resource budgets, statistical plans, and evidence policies before scarce hardware time is consumed.

The key design principle is staged confidence: every pipeline stage should eliminate a class of failure at the cheapest layer that can detect it. Transpiler target metadata, primitive contracts, resource estimators, and reservation systems all become part of release engineering [R106] [R107] [R108] [R113].

60.1 Pipeline shape

flowchart LR
    Commit[Commit] --> Lint[Lint and type checks]
    Lint --> Unit[Classical unit tests]
    Unit --> Circuit[Circuit invariant tests]
    Circuit --> Compile[Target compilation]
    Compile --> Estimate[Cost and resource estimate]
    Estimate --> Sim[Simulation / emulation]
    Sim --> Canary[Hardware canary]
    Canary --> Promote[Promotion gate]

The QPU is late in the pipeline. If the QPU is the first meaningful test, the platform is leaking cost.

60.2 What to test before hardware

flowchart TB
    PreQPU[Pre-QPU validation] --> Math[Math invariants]
    PreQPU --> Shape[Circuit shape]
    PreQPU --> Target[Target compatibility]
    PreQPU --> Budget[Budget compliance]
    PreQPU --> Evidence[Evidence completeness]

Examples:

60.3 Circuit invariant tests

Circuit tests should be explicit because many bugs produce plausible distributions.

flowchart LR
    Circuit[Circuit] --> Width[Width invariant]
    Circuit --> Params[Parameter invariant]
    Circuit --> Measure[Measurement invariant]
    Circuit --> Symmetry[Symmetry invariant]
    Circuit --> Ref[Reference small case]

Useful invariants include:

• number of qubits matches the model
• parameter vector length matches the ansatz
• all required qubits are measured
• conserved quantities remain conserved in noiseless simulation
• small cases match exact classical solutions

60.4 Target-aware compilation gates

A release candidate must compile against declared targets.

flowchart TB
    Candidate[Release candidate] --> Targets{Declared targets}
    Targets --> T1[Target A]
    Targets --> T2[Target B]
    Targets --> T3[Simulator]
    T1 --> Report[Compilation report]
    T2 --> Report
    T3 --> Report
    Report --> Gate{Pass policy?}
    Gate -- yes --> Next[Next stage]
    Gate -- no --> Block[Block release]

A target-aware gate should record:

• target version
• basis set
• connectivity or interaction graph
• timing constraints
• dynamic-control capability
• resulting depth and two-qubit count
• predicted runtime or shot envelope

Qiskit's Target abstraction exists to tell the compiler what a backend can support, including instruction properties and timing information [R113]. The operational pattern is broader than any one framework: make target capability an input to CI, not tribal knowledge.

60.5 Resource-estimation gate

Resource estimation belongs in CI even before fault-tolerant machines are available.

flowchart LR
    Algorithm[Algorithm version] --> Logical[Logical resource estimate]
    Logical --> Physical[Physical assumptions]
    Physical --> Envelope[Runtime / qubits / error budget]
    Envelope --> Policy{Within roadmap envelope?}
    Policy -- yes --> Track[Track trend]
    Policy -- no --> Reject[Reject or redesign]

The Azure Quantum Resource Estimator is one example of tooling that exposes estimates across logical resources, physical qubits, runtime, error-correction choices, and hardware assumptions [R108]. Use resource estimation to prevent algorithmic debt from growing unnoticed.

60.6 Hardware canaries

A hardware canary is a small experiment that protects a larger run.

sequenceDiagram
    participant CI as CI Pipeline
    participant QPU as QPU Target
    participant Metrics as Metrics Store
    participant Gate as Release Gate
    CI->>QPU: submit canary workload
    QPU-->>CI: canary result
    CI->>Metrics: compare with baseline
    Metrics-->>Gate: pass/fail + diagnostics
    Gate-->>CI: proceed or hold

Canaries should be cheap, representative, and stable. They are not benchmarks for marketing. They are tripwires for target drift.

60.7 Release channels

stateDiagram-v2
    [*] --> Experimental
    Experimental --> Candidate: tests pass
    Candidate --> LimitedHardware: hardware canary pass
    LimitedHardware --> Production: review approved
    Candidate --> Experimental: failed gate
    LimitedHardware --> Candidate: drift detected
    Production --> Deprecated: superseded

Release channels help users interpret trust:

60.8 CI/CD for calibration-dependent code

Some quantum programs depend on calibration assumptions. CI must separate source changes from target changes.

flowchart TB
    SourceChange[Source change] --> Pipeline[Pipeline]
    TargetChange[Target / calibration change] --> Pipeline
    Pipeline --> Matrix{Test matrix}
    Matrix --> OldSourceNewTarget[Old source / new target]
    Matrix --> NewSourceOldTarget[New source / old target]
    Matrix --> NewSourceNewTarget[New source / new target]

This matrix reveals whether a regression came from code, target drift, or interaction between them.

60.9 Promotion checklist

Before promoting a quantum workflow, require:

• deterministic construction from source
• manifest schema validation
• exact or simulator baseline for small cases
• target compilation report
• resource estimate
• QPU canary result when hardware is involved
• evidence package URI
• reviewer sign-off

flowchart LR
    Checklist[Promotion checklist] --> Pass{All required artifacts?}
    Pass -- no --> Hold[Hold]
    Pass -- yes --> Sign[Sign release]
    Sign --> Registry[Publish workflow artifact]

60.10 Operating rule

Quantum CI/CD should protect both correctness and hardware capacity.

flowchart LR
    CI[CI/CD] --> Correctness[Correctness protection]
    CI --> Capacity[Capacity protection]
    CI --> Trust[Trust protection]

The pipeline is successful when fewer invalid experiments reach hardware and more valid results survive review.