CI/CD Templates and CLI Contracts — Operating Quantum Computers

This appendix provides implementation templates for the CI/CD and developer-experience chapters. Treat them as starting points, not standards.

K.1 Workflow manifest

Illustrative listing · yaml

apiVersion: quantum.platform/v1
kind: QuantumWorkflow
metadata:
  name: h2-vqe-baseline
  owner: chemistry-platform
  labels:
    workload: estimation
    assurance: L1
spec:
  source:
    repository: git@example.com:quantum/h2-vqe.git
    revision: 7b2d4fa
  entrypoint:
    module: workflows.vqe
    function: run
  target:
    profile: ibm-runtime-estimator-v2
    allowedBackends:
      - ibm_fez
      - simulator-noise-h2
  budget:
    maxShots: 200000
    maxSpendUsd: 500
    maxWallClockMinutes: 120
  evidence:
    required: true
    retentionClass: decision

K.2 CI pipeline skeleton

Diagram loads as you read

K.2 CI pipeline skeleton · Figure 1

View diagram source

flowchart LR
    Checkout[checkout] --> Install[install]
    Install --> Unit[unit tests]
    Unit --> Circuit[circuit invariants]
    Circuit --> Compile[compile targets]
    Compile --> Estimate[resource estimate]
    Estimate --> Sim[simulation]
    Sim --> Canary[optional hardware canary]
    Canary --> Publish[publish artifact]

Illustrative listing · yaml

name: quantum-workflow-ci
on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install
        run: pip install -r requirements.txt
      - name: Unit tests
        run: pytest tests/unit
      - name: Circuit invariants
        run: quantumctl validate circuits --manifest experiments/*.yaml
      - name: Compile target matrix
        run: quantumctl compile --manifest experiments/*.yaml --targets targets/*.yaml
      - name: Resource estimates
        run: quantumctl estimate --manifest experiments/*.yaml --policy policies/resource.yaml
      - name: Simulation smoke tests
        run: quantumctl simulate --manifest experiments/*.yaml --shots 1000

K.3 Release gate policy

Diagram loads as you read

K.3 Release gate policy · Figure 2

View diagram source

flowchart TB
    Gate[Release gate] --> Required[Required checks]
    Required --> Static[static]
    Required --> Sim[simulation]
    Required --> Budget[budget]
    Required --> Evidence[evidence]
    Required --> Review[review]

Illustrative listing · yaml

apiVersion: quantum.platform/v1
kind: ReleaseGate
metadata:
  name: decision-grade-v1
spec:
  requiredChecks:
    - type: schema
    - type: source-hash
    - type: circuit-invariants
    - type: target-compilation
    - type: resource-estimate
    - type: simulator-baseline
    - type: evidence-package
    - type: reviewer-approval
  thresholds:
    maxTwoQubitDepthIncreasePct: 10
    maxEstimatedSpendUsd: 1000
    minCanaryPassRate: 0.95

K.4 CLI contract

Diagram loads as you read

K.4 CLI contract · Figure 3

View diagram source

flowchart LR
    quantumctl[quantumctl] --> Validate[validate]
    quantumctl --> Compile[compile]
    quantumctl --> Estimate[estimate]
    quantumctl --> Run[run]
    quantumctl --> Evidence[evidence]
    quantumctl --> Promote[promote]

Suggested commands:

Illustrative listing · bash

quantumctl validate --manifest experiments/vqe.yaml
quantumctl compile --manifest experiments/vqe.yaml --target targets/ibm.yaml
quantumctl estimate --manifest experiments/vqe.yaml --target targets/ftqc.yaml
quantumctl run --manifest experiments/vqe.yaml --mode simulator
quantumctl run --manifest experiments/vqe.yaml --mode qpu --assurance L1
quantumctl evidence show exp_2026_04_19_001
quantumctl promote workflow h2-vqe-baseline --gate decision-grade-v1

K.5 Exit codes

Exit code	Meaning
0	success
10	schema or manifest error
20	circuit invariant failure
30	target incompatibility
40	budget or policy failure
50	runtime failure
60	evidence publication failure
70	review gate failure

K.6 Failure payload

Illustrative listing · json

{
  "status": "failed",
  "failure_type": "target_incompatibility",
  "message": "Circuit requires mid-circuit reset but target profile does not advertise reset support.",
  "manifest": "experiments/qec-probe.yaml",
  "target_profile": "targets/device-a-2026-04-19.yaml",
  "recommended_action": "Choose a target with reset support or rewrite the workload."
}

K.7 Hardware canary manifest

Illustrative listing · yaml

apiVersion: quantum.platform/v1
kind: Canary
metadata:
  name: bell-readout-canary
spec:
  targetSelector:
    family: superconducting
  schedule:
    beforeDecisionRuns: true
  circuit:
    type: bell_pair
    qubits: [0, 1]
  thresholds:
    minFidelity: 0.85
    maxReadoutAsymmetry: 0.08
  evidence:
    retentionClass: benchmark

K.8 Promotion state machine

Diagram loads as you read

K.8 Promotion state machine · Figure 4

View diagram source

stateDiagram-v2
    [*] --> Draft
    Draft --> Candidate: validate
    Candidate --> Canary: preflight passed
    Canary --> Review: canary passed
    Review --> Production: approved
    Candidate --> Draft: failed preflight
    Canary --> Candidate: failed canary
    Review --> Candidate: changes requested
    Production --> Deprecated: replaced