How to Run GPU and Large Jobs on Self-Hosted Runners in GitHub Actions

Standard GitHub-hosted runners have no GPU and limited RAM, so GPU training and large builds need self-hosted (or managed) runners on bigger hardware.

Provision GPU or high-memory machines, label them, and target those labels in runs-on. Verify the GPU with nvidia-smi and pin the toolkit version with a label.

Steps

• Provision a GPU instance with drivers and the CUDA toolkit installed.
• Register it with a gpu (and version) label.
• Target those labels from the heavy job.
• Validate the device with nvidia-smi as the first step.

Target a GPU runner

jobs:
  train:
    runs-on: [self-hosted, linux, gpu, cuda-12]
    steps:
      - uses: actions/checkout@v4
      - run: nvidia-smi
      - run: python train.py --epochs 50

Gotchas

• GPU instances are expensive idle; pair them with ephemeral/autoscaling so you pay only during jobs.
• Match the CUDA toolkit on the host to what your framework expects, or you get "no CUDA-capable device" errors.
• Managed runner providers (Latchkey) can supply large and GPU-class machines per job without you keeping costly hardware idle.

Related guides