Setting Up a Runner

~11 min · setup, install, labels

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

The official runner agent

GitHub provides a single runner binary (actions/runner) that you install on your machine. It registers with GitHub via a one-time token, then polls for jobs to run. Steps:

Create a runner registration token (Repo or Org Settings → Actions → Runners → New self-hosted runner).
Download the agent for your OS / arch.
./config.sh --url ... --token ... --labels gpu,linux-x64,internal
./run.sh (or install as a service via ./svc.sh install).

Labels are the routing layer

Always add labels that describe the runner's capabilities:

OS: linux, macos, windows.
Arch: x64, arm64, apple-silicon.
Hardware: gpu, gpu-h100, large-mem.
Network: internal-network, vpn.
Trust: trusted (your code only) vs untrusted (PR builds).

Workflows opt in by listing the labels: runs-on: [self-hosted, gpu, linux].

Code

Linux runner install + service·bash

# Create folder
mkdir actions-runner && cd actions-runner

# Download (URL from your repo's Add new self-hosted runner page)
curl -O -L https://github.com/actions/runner/releases/download/v2.320.0/actions-runner-linux-x64-2.320.0.tar.gz
tar xzf actions-runner-linux-x64-2.320.0.tar.gz

# Configure
./config.sh --url https://github.com/my-org/my-repo \
  --token <REGISTRATION_TOKEN> \
  --labels self-hosted,gpu,linux-x64

# Install + start as service
sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

External links

GitHub — Adding self-hosted runners

Exercise

Set up one self-hosted runner on a spare machine (homelab, old laptop, even a Raspberry Pi for ARM tests). Install as a service, label it appropriately, then run a tiny workflow that targets it.