GitHub Actions Tutorial — Setup Runners

1 minute read

Setup Runners

Setting up a self-hosted runner involves downloading the runner application, configuring it to connect to your repository or organization, and starting the service.

Runner Levels

Level	Scope	Best For
Repository	Single repo	Small projects, testing
Organization	All repos in org	Shared infrastructure
Enterprise	All orgs in enterprise	Large-scale deployments

Installation Steps (Linux)

1. Create a Runner Directory

mkdir actions-runner && cd actions-runner

2. Download the Runner

From your repository → Settings → Actions → Runners → New self-hosted runner:

# Download (URL provided by GitHub)
curl -o actions-runner-linux-x64-2.319.1.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.319.1/actions-runner-linux-x64-2.319.1.tar.gz

# Extract
tar xzf ./actions-runner-linux-x64-2.319.1.tar.gz

3. Configure

./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO \
            --token YOUR_REGISTRATION_TOKEN

The token is short-lived (1 hour) and provided in the GitHub UI.

4. Start

# Interactive (foreground)
./run.sh

# As a service (background)
sudo ./svc.sh install
sudo ./svc.sh start

Service Management (Linux)

# Install as systemd service
sudo ./svc.sh install

# Start/stop/status
sudo ./svc.sh start
sudo ./svc.sh stop
sudo ./svc.sh status

# Uninstall
sudo ./svc.sh uninstall

macOS Setup

# Download macOS runner
curl -o actions-runner-osx-x64-2.319.1.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.319.1/actions-runner-osx-x64-2.319.1.tar.gz

tar xzf ./actions-runner-osx-x64-2.319.1.tar.gz

# Configure
./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO \
            --token YOUR_TOKEN

# Install as launchd service
./svc.sh install
./svc.sh start

Using Self-Hosted Runners in Workflows

jobs:
  build:
    runs-on: self-hosted         # use any self-hosted runner
    steps:
      - uses: actions/checkout@v4
      - run: echo "Running on self-hosted runner"

Target by Labels

jobs:
  build:
    runs-on: [self-hosted, linux, x64, gpu]    # match all labels
    steps:
      - run: nvidia-smi

Every self-hosted runner automatically gets these labels:

self-hosted
OS: linux, macOS, or windows
Architecture: x64, ARM, or ARM64

Runner Requirements

Requirement	Detail
OS	Linux, macOS 10.13+, Windows Server 2019+
Architecture	x64 or ARM64
Software	Git, Docker (optional), Node.js (optional)
Network	HTTPS outbound to `github.com` and `*.actions.githubusercontent.com`
Disk	At least 14 GB free (for runner + workspace)

Common Mistakes

Mistake	Fix
Token expired	Tokens last 1 hour; generate a new one from Settings
Runner appears offline	Check the service status and network connectivity
Jobs stuck in queue	Verify labels match between workflow and runner
Permission denied	Run the service as a user with appropriate permissions

Quick Reference

Command	Purpose
`./config.sh --url ... --token ...`	Register runner
`./run.sh`	Start interactively
`sudo ./svc.sh install && start`	Run as service
`./config.sh remove --token ...`	Unregister runner
`runs-on: self-hosted`	Use in workflow

← Back to: Chapter 12: Self-Hosted Runners

Next: Runner Groups & Labels →

Share on

Twitter Facebook LinkedIn