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.
Comprehensive skill for managing self-hosted GitHub Actions runners with dedicated user isolation and systemd service management.
runner user, not dev user~/.agent/skills mount# 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
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.*
See comprehensive documentation: docs/SELF_HOSTED_RUNNER_SETUP.md
The complete setup guide covers:
/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
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:
sudo systemctl start ...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.*
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
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
Workflows running on self-hosted runners should be aware of:
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
Runner user should have Beads CLI installed:
- name: Install Beads CLI
run: |
pip install beads-cli
Use mise for consistent toolchain:
- name: Setup Python via mise
uses: ./.github/actions/setup-python-mise
Runner user should have:
Consider:
docs/SELF_HOSTED_RUNNER_SETUP.md - Complete setup guidedocs/SKILLS_PLANE.md - Skills mount architecturedocs/DX_BOOTSTRAP_CONTRACT.md - Session startup requirementsWhen working on runner-related tasks:
sudo journalctl -u actions.runner...sudo -u runner ./run.shTo set up self-hosted runners on a new VM:
sudo useradd -m -s /bin/bash -c "GitHub Actions Runner" runnersudo -u runner git clone https://github.com/stars-end/agent-skills.git ~runner/agent-skillssudo -u runner bash -c 'mkdir -p ~/.agent && ln -sfn ~/agent-skills ~/.agent/skills'docs/SELF_HOSTED_RUNNER_SETUP.md