Run GitHub Actions on bare metal

Dedicated hardware, a disposable environment for each job

Running GitHub Actions on bare metal means supplying the physical machines that execute your CI. A self-hosted runner connects those machines to GitHub. With Baremetal, the runner lives inside a fresh virtual machine on your hardware: Tart on Apple Silicon, or QEMU/KVM on Linux. Your job does not run directly on the host operating system.

This fits teams that already have Macs for Apple builds or Linux servers for compilation, containers and tests. You choose the hardware and VM image; Baremetal handles runner registration, scheduling and cleanup.

Persistent runners or ephemeral VMs?

A persistent runner reuses its working environment. That makes local caches convenient, but installed packages, background processes and files can affect the next build. Your team needs to maintain and clean that environment.

An ephemeral Baremetal runner accepts one job and is then removed with its VM. The next job starts from the base image again. Put required tools in that image, use an external build cache where appropriate, and upload artifacts before the job finishes. VM startup and image downloads are costs to include when comparing approaches.

GitHub recommends ephemeral runners for autoscaling. See the GitHub self-hosted runner reference and our runner security model.

Choose a host for your workload

• Apple builds: use an Apple Silicon Mac and a macOS image with your Xcode version. See self-hosted macOS runners.
• Linux builds: use a Linux host with hardware virtualization and /dev/kvm. Jobs run in QEMU/KVM guests with their own kernel.
• Docker workloads: Docker and service containers run inside the Linux guest. The host does not need to become a shared Docker build environment.

Leave CPU, memory and disk space for the host, images and concurrent guests. Autoscaling uses the capacity you supply; it cannot create additional physical machines.

Connect a workflow to your own hardware

1. Create a workspace and connect the GitHub organization or repository you administer.
2. Use the dashboard’s one-time join command to install an agent on your host.
3. Create a pool with a VM image, CPU and memory allocation, and runner labels.
4. Copy the pool’s labels into the workflow’s runs-on field.

For example, after giving a Linux pool the custom label baremetal-linux, this manually triggered workflow checks which environment received the job:

name: Check my runner
on: workflow_dispatch
permissions:
  contents: read
jobs:
  check:
    runs-on: [self-hosted, linux, x64, baremetal-linux]
    steps:
      - run: uname -a

The labels must match your actual pool. Follow the setup guide for enrollment, images and troubleshooting.

Compare the full cost of CI

Baremetal is free during beta and does not charge for compute minutes on your hardware. Your machines still have costs: purchase or rental, power, maintenance, networking and the time spent maintaining images. Compare those costs and measured job durations with your existing CI bill before choosing capacity.

Start with one representative workflow. Measure queue time, runtime and reliability, then decide whether to keep warm runners available or let idle capacity scale down.

Plan and troubleshoot your runners

• What survives an ephemeral CI job?
• Compare the full cost of self-hosted and hosted runners
• Diagnose a job stuck waiting for a runner