PantheonSim / GitHub Actions

CUDA and HIP tests in GitHub Actions, without a GPU

PantheonSim, the GPU simulator for CUDA and ROCm, ships a GitHub Action for a problem GPU teams know: GitHub’s hosted runners have no GPU, so GPU code usually goes untested until someone has a card free. The action gives a job simulated NVIDIA or AMD GPUs: CUDA and HIP code compiles, and its tests run, on every push and pull request.

Add it to a workflow

One step, after checkout. Everything after it in the job sees the GPUs you asked for.

# .github/workflows/cuda.yml
name: CUDA tests
on: [push, pull_request]

jobs:
  cuda-tests:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: pantheongpu/pantheonsim@main
        with:
          gpu: nvidia/h100
          count: 2
      - run: |
          nvidia-smi -L
          nvcc -arch=compute_90 my_test.cu -o my_test
          vgpu run ./my_test

AMD and HIP

Name an Instinct profile and the action installs ROCm’s own hipcc instead of the CUDA toolkit. It installs only the compiler: the simulator is the HIP runtime, so no driver or ROCm runtime comes with it.

      - uses: pantheongpu/pantheonsim@main
        with:
          gpu: amd/mi300x
          count: 2
      - run: |
          rocm-smi
          hipcc --offload-arch=gfx942 my_test.hip -o my_test
          ./my_test

A program hipcc built runs directly, as above, or under vgpu run: the action points ROCm’s libamdhip64 at the simulator, so ctest and test scripts work unchanged. rocm_agent_enumerator reports the simulated cards, so hipcc with no --offload-arch builds for them, as it would on a real machine.

CUDA and ROCm versions

By default an NVIDIA job gets Ubuntu’s CUDA toolkit (CUDA 12.0 on ubuntu-24.04) and an AMD job gets ROCm 7.1. Name a version to get that one instead, from NVIDIA’s or AMD’s own repository:

      - uses: pantheongpu/pantheonsim@main
        with:
          gpu: nvidia/h100
          cuda-toolkit: '12.6'     # or '13.0'

What it does

1. Installs CMake, Ninja and a C++ compiler, then the compiler for the GPU: Ubuntu’s CUDA toolkit with the GCC 12 its nvcc needs, the nvcc of the CUDA version you named, or, for an AMD GPU, ROCm’s hipcc.
2. Builds the simulator at the ref the job named, and caches the build against a hash of its source and the toolkit version, so later runs skip it.
3. Puts the simulator’s tools (nvidia-smi, rocm-smi, amd-smi, rocm_agent_enumerator, vgpu) first on PATH and sets VGPU_GPU, VGPU_DEVICE_COUNT and VGPU_SHIM_DIR for the rest of the job (and, with the apt toolkit, NVCC_PREPEND_FLAGS=-ccbin g++-12).

After it, nvidia-smi or rocm-smi reports the GPUs you asked for, nvcc is the real compiler with -cudart shared added (so unmodified build systems link the runtime the simulator stands in for), and vgpu run ./program runs a program on the simulated GPUs.

Inputs

Outputs

Testing on every GPU

A result that depends on the card is the bug CI on one GPU never finds. vgpu test --matrix runs the same binary on every measured NVIDIA profile and compares the outputs; it exits 3 when a profile differs and 4 when the program did not run at all. Build it for the oldest architecture you support:

      - run: |
          nvcc -arch=compute_75 vectoradd.cu -o vectoradd
          vgpu test --matrix ./vectoradd | tee matrix.txt
          grep -q ' 0 different' matrix.txt

Things to know

• Build kernels for an architecture the profile supports: -arch=compute_75 runs on a T4 and every newer card, compute_90 needs Hopper. On AMD, build for the card’s target: gfx942 for the MI300X and MI325X, gfx950 for the MI350X.
• Check return codes in your tests. A refused kernel or an unsupported call returns its CUDA or HIP error and prints why, but the program carries on, so a test that ignores the code can still exit 0.
• The simulator’s CUDA libraries are built against the job’s toolkit, so their version always matches the nvcc that compiled the program.
• It checks behaviour, not performance: timings mean nothing here. Keep a run on physical GPUs before a release.
• Linux runners only: ubuntu-24.04, ubuntu-22.04 and container jobs. On 22.04, Ubuntu’s own CUDA toolkit is too old, so an NVIDIA job there gets CUDA 12.6 from NVIDIA. The first run builds the simulator; later runs restore it from the cache.
• Not on GitHub? scripts/ci-setup.sh in the repository does what the action does for any CI system that can run a shell script on Ubuntu; its instructions say which parts are untested.
• The AMD side is newer than the NVIDIA one. The HIP runtime is simulated, and anything not implemented is refused by name.