github-runner-setup

name	github-runner-setup
description	GitHub Actions self-hosted runner setup and maintenance. Use when setting up dedicated runner users, migrating runners from personal accounts, troubleshooting runner issues, or implementing runner isolation. Covers systemd services, environment isolation, and skills plane integration.
tags	["github-actions","devops","runner","systemd","infrastructure"]
keywords	self-hosted runner, github actions, systemd, runner isolation, runner migration, runner troubleshooting

GitHub Runner Setup & Maintenance

Comprehensive skill for managing self-hosted GitHub Actions runners with dedicated user isolation and systemd service management.

When to Use This Skill

• Setting up new self-hosted runners with dedicated user accounts
• Migrating runners from personal user accounts to dedicated runner users
• Troubleshooting runner connectivity or execution issues
• Implementing environment isolation to prevent CI/dev environment pollution
• Configuring systemd services for auto-restart on reboot
• Fixing workflow issues related to runner permissions or environment

Key Principles

1. Environment Isolation: Runners run as dedicated runner user, not dev user
2. Systemd Management: Services auto-start on reboot, managed via systemd
3. Skills Plane Integration: Runner user has permanent ~/.agent/skills mount
4. Security: Minimal permissions for runner user (no sudo by default)

Quick Reference

Check Runner Status

# List active runners on GitHub
cd ~/prime-radiant-ai
gh api repos/stars-end/prime-radiant-ai/actions/runners --jq '.runners[] | {id, name, status, busy}'

# Check systemd service status
sudo systemctl status 'actions.runner.stars-end-prime-radiant-ai.*'

# View runner logs
sudo journalctl -u 'actions.runner.stars-end-prime-radiant-ai.*' -f

Common Tasks

Restart a Runner:

sudo systemctl restart actions.runner.stars-end-prime-radiant-ai.*

Update agent-skills for runner user:

sudo -u runner git -C ~runner/agent-skills pull origin main

Switch to runner user for debugging:

sudo su - runner

Regenerate runner token (tokens expire after a few hours):

# Generate new token
cd ~/prime-radiant-ai
TOKEN=$(gh api --method POST repos/stars-end/prime-radiant-ai/actions/runners/registration-token --jq .token)

# Stop service, reconfigure, restart
sudo systemctl stop actions.runner.stars-end-prime-radiant-ai.*
cd /home/runner/actions-runner-prime-radiant
sudo -u runner ./config.sh remove
sudo -u runner ./config.sh --url https://github.com/stars-end/prime-radiant-ai --token $TOKEN --name "$(hostname -s)-prime-radiant" --labels "self-hosted,linux,x64" --work _work --unattended
sudo systemctl start actions.runner.stars-end-prime-radiant-ai.*

Full Setup Guide

See comprehensive documentation: docs/SELF_HOSTED_RUNNER_SETUP.md

The complete setup guide covers:

• Creating dedicated runner user
• Installing runners with proper isolation
• Systemd service configuration
• Migration from personal user runners
• Troubleshooting common issues
• Security considerations
• Maintenance procedures

Architecture

/home/runner/
├── .agent/
│   └── skills -> /home/runner/agent-skills
├── agent-skills/           # Cloned from stars-end/agent-skills
├── actions-runner-prime-radiant/
│   ├── config.sh
│   ├── run.sh
│   └── svc.sh
└── actions-runner-affordabot/
    ├── config.sh
    ├── run.sh
    └── svc.sh

Troubleshooting

Runner Not Appearing in GitHub

Symptoms: Runner shows as offline or doesn't appear in GitHub UI

Debug:

# Check service status
sudo systemctl status actions.runner.stars-end-prime-radiant-ai.*

# Check recent logs for errors
sudo journalctl -u actions.runner.stars-end-prime-radiant-ai.* -n 50

# Try running manually to see connection errors
sudo -u runner bash
cd ~/actions-runner-prime-radiant
./run.sh  # Press Ctrl+C to stop

Common causes:

• Token expired → Regenerate token and reconfigure
• Network issues → Check firewall rules for GitHub API access
• Service not running → sudo systemctl start ...

Workflow Fails with "Unable to locate executable file: unzip"

Symptoms: Setup actions (actions/setup-bun, actions/setup-node, etc.) fail with "unzip not found"

Solution: Install missing system utilities

# Install unzip and zip system-wide
sudo apt-get update
sudo apt-get install -y unzip zip

# Verify
sudo -u runner which unzip  # Should show /usr/bin/unzip

# Restart runner to pick up changes
sudo systemctl restart actions.runner.stars-end-prime-radiant-ai.*

Workflow Needs Python 3.13

Symptoms: Workflows fail with wrong Python version or Python 3.13 not found

Solution: Install Python 3.13 via mise

# Install mise for runner user (if not already)
sudo -u runner bash -c 'curl https://mise.run | sh'

# Configure shell
sudo -u runner bash -c 'echo "export PATH=\"\$HOME/.local/bin:\$PATH\"" >> ~/.bashrc'
sudo -u runner bash -c 'echo "eval \"\$(mise activate bash)\"" >> ~/.bashrc'

# Install Python 3.13
sudo -u runner bash -c 'export PATH="$HOME/.local/bin:$PATH" && mise use --global python@3.13 && mise install'

# Verify
sudo -u runner bash --login -c 'python --version'  # Should show 3.13.x

# Restart runner
sudo systemctl restart actions.runner.stars-end-prime-radiant-ai.*

Workflow Fails with "Permission Denied"

Symptoms: Workflows fail with permission errors accessing files/directories

Solution: Runner user may need additional permissions

# Add to docker group (if workflows use Docker)
sudo usermod -aG docker runner

# For specific directory access, use ACLs
sudo setfacl -m u:runner:rwx /path/to/directory

# Restart runner service after group changes
sudo systemctl restart actions.runner.stars-end-prime-radiant-ai.*

Skills Mount Corruption (Dev Environment)

Symptoms: ~/.agent/skills in dev user environment points to runner workspace

Root Cause: Old workflow configuration that ran as dev user and modified global symlink

Fix:

# Fix dev user's symlink
rm -f ~/.agent/skills && ln -sfn ~/agent-skills ~/.agent/skills

# Verify runner's symlink is isolated (should NOT affect dev user)
sudo -u runner ls -la ~/.agent/skills
# Should show: /home/runner/.agent/skills -> /home/runner/agent-skills

Prevention: Ensure workflows don't create ~/.agent/skills symlinks if using dedicated runner user

Runner Service Won't Start

Debug steps:

# Check if service file exists
ls -la /etc/systemd/system/actions.runner.stars-end-*

# Reload systemd daemon
sudo systemctl daemon-reload

# Check for failed units
sudo systemctl --failed

# View detailed service errors
sudo systemctl status actions.runner.stars-end-prime-radiant-ai.* -l

Workflow Integration

Workflows running on self-hosted runners should be aware of:

Skills Environment

Runner user has permanent skills mount. Workflows should verify rather than recreate:

- name: Setup Skills Environment
  run: |
    # Runner user already has permanent skills mount at ~/.agent/skills → ~/agent-skills
    # Verify the existing mount
    ls -la ~/.agent/skills

    # Workflow checkout is available at $PWD/agent-skills if needed
    ls -la $PWD/agent-skills

Beads CLI

Runner user should have Beads CLI installed:

- name: Install Beads CLI
  run: |
    pip install beads-cli

Python/Node Setup

Use mise for consistent toolchain:

- name: Setup Python via mise
  uses: ./.github/actions/setup-python-mise

Security Considerations

Minimal Permissions

Runner user should have:

• ✅ Read/write to its own home directory
• ✅ Execute permissions for required tools (git, docker, mise, etc.)
• ❌ NO sudo access (unless workflows explicitly require it)
• ❌ NO access to other users' home directories

Secrets Handling

• Never log secrets in workflow output
• Use GitHub secrets for sensitive values
• Runner has access to repository secrets during workflow execution
• Secrets are automatically masked in logs

Network Isolation

Consider:

• Firewall rules limiting runner's network access
• VPN/bastion for accessing internal resources
• Separate runner for public vs private repos

Related Documentation

• docs/SELF_HOSTED_RUNNER_SETUP.md - Complete setup guide
• docs/SKILLS_PLANE.md - Skills mount architecture
• docs/DX_BOOTSTRAP_CONTRACT.md - Session startup requirements

Agent Guidance

When working on runner-related tasks:

1. First, check runner status on GitHub and systemd
2. Read logs before making changes: sudo journalctl -u actions.runner...
3. Test manually before modifying systemd services: sudo -u runner ./run.sh
4. Document changes in commit messages with Feature-Key trailers
5. Verify isolation after changes: runner user changes shouldn't affect dev user

Quick Start for New VM

To set up self-hosted runners on a new VM:

1. Create runner user: sudo useradd -m -s /bin/bash -c "GitHub Actions Runner" runner
2. Clone agent-skills for runner: sudo -u runner git clone https://github.com/stars-end/agent-skills.git ~runner/agent-skills
3. Setup skills mount: sudo -u runner bash -c 'mkdir -p ~/.agent && ln -sfn ~/agent-skills ~/.agent/skills'
4. Follow full setup guide in docs/SELF_HOSTED_RUNNER_SETUP.md

Notes

• Runner tokens expire after a few hours; keep track if reconfiguring
• Systemd services persist across reboots (unlike nohup/screen)
• Runner isolation prevents the "skills mount corruption" problem
• Each repository needs its own runner registration
• Runners can be shared across repos by adding multiple repo registrations