RealHW

Developer docs for workloads that need real hardware.

Run your first job Run an image workload

RealHW gives your project one runner identity and a hardware-aware execution plane. Keep using familiar GitLab tags for ordinary jobs, then ask for GPUs, KVM, NICs, SR-IOV, NUMA placement, hugepages, or a specific CPU architecture when the workload needs them.

qemu-tests:
  tags:
    - realhw
    - arch:x86_64
    - kvm
  script:
    - ./run-qemu-tests.sh
  artifacts:
    when: always
    paths:
      - results/

The runner admits the request before the job starts, projects only allowlisted devices, streams logs through the lifecycle, and returns the job result to GitLab.

Choose your path

Connect GitLab

Create a project runner, add the tags you need, and let RealHW route each job.

Select hardware

Browse the marker catalog and compose a request from stable capability tags.

Run an image

Launch an existing OCI image, request KVM, and collect logs and artifacts.

Debug placement

Trace tags, capacity, admission, and unsupported requests when a job waits.

Developer reference

Need	Start here
GitLab job examples	CI examples
CPU and architecture	CPU and architecture
GPUs and device counts	GPU markers
KVM, artifacts, and cloud-init	Run an image workload
Runner selection failures	Debug runner selection