Github Runner Setup

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 "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