How to Build and Test on a Self-Hosted GPU Runner in GitHub Actions

A labeled GPU runner lets CUDA jobs run where GitHub-hosted runners cannot.

Register a self-hosted runner with a gpu label on a GPU host, then target it with runs-on and confirm the GPU is visible.

Steps

• Register the runner on a GPU machine with a custom gpu label.
• Target it via runs-on: [self-hosted, gpu].
• Verify the GPU with nvidia-smi before the workload.

Workflow

jobs:
  train:
    runs-on: [self-hosted, gpu]
    steps:
      - uses: actions/checkout@v4
      - run: nvidia-smi
      - run: pip install -r requirements.txt && python train.py

Gotchas

• The host needs matching NVIDIA drivers and the CUDA toolkit installed.
• Latchkey can manage GPU runners for you with self-healing provisioning at lower cost than an always-on box.

Related guides