Self-hosted GitHub Actions runner management via Podman Quadlet. Supports multi-instance pools with ephemeral storage, automatic token generation, and rolling updates. Use when users need to set up CI/CD runners for their GitHub repositories.
/plugin marketplace add atrawog/bazzite-ai-plugins/plugin install atrawog-bazzite-ai-bazzite-ai@atrawog/bazzite-ai-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
The runners command manages self-hosted GitHub Actions runners using Podman Quadlet containers. It supports multi-instance pools with ephemeral storage for clean builds.
Key Concept: Each runner instance connects to a GitHub repository and picks up workflow jobs. Ephemeral storage ensures each job starts with a clean state.
| Action | Command | Description |
|---|---|---|
| Config | ujust runners config <REPO_URL> <N> [IMAGE] [WORKSPACE] | Configure runner N for repo |
| Start | ujust runners start [N|all] | Start runner(s) |
| Stop | ujust runners stop [N|all] | Stop runner(s) |
| Restart | ujust runners restart [N|all] | Restart runner(s) |
| Update | ujust runners update [N|all] | Update to latest image |
| Rolling update | ujust runners rolling-update | Update with zero downtime |
| Sync | ujust runners sync [N] | Sync config from source |
| Logs | ujust runners logs [N] [LINES] | View logs |
| List | ujust runners list | List all runners |
| Shell | ujust runners shell [CMD] [N] | Open shell in container |
| Delete | ujust runners delete [N|all] | Remove runner(s) and images |
# 1. Authenticate GitHub CLI
gh auth login
# 2. Verify authentication
gh auth status
ujust runners config <REPO_URL> <INSTANCE> [IMAGE] [WORKSPACE]
| Parameter | Required | Description |
|---|---|---|
REPO_URL | Yes | GitHub repository URL |
INSTANCE | Yes | Instance number (1, 2, 3...) |
IMAGE | No | Container image or tag (default: stable) |
WORKSPACE | No | Optional additional mount to /workspace |
# Basic runner
ujust runners config https://github.com/owner/repo 1
# Runner with testing tag
ujust runners config https://github.com/owner/repo 1 testing
# Runner with workspace mount
ujust runners config https://github.com/owner/repo 1 latest /home/user
# Custom image with workspace
ujust runners config https://github.com/owner/repo 1 "ghcr.io/custom/runner:v1" /projects
# Runner pool for a repository
ujust runners config https://github.com/owner/repo 1
ujust runners config https://github.com/owner/repo 2
ujust runners config https://github.com/owner/repo 3
# Start all
ujust runners start all
Running config when already configured will update the existing configuration, preserving values not explicitly changed.
# Interactive bash shell
ujust runners shell
# Run specific command
ujust runners shell "df -h"
# Shell in specific instance
ujust runners shell "cat /config/runner.env" 2
# Single runner
ujust runners start 1
ujust runners stop 1
# All runners
ujust runners start all
ujust runners stop all
# Fast update (stops runner briefly)
ujust runners update 1
# Rolling update (zero-downtime)
ujust runners rolling-update
Rolling update:
# Follow logs
ujust runners logs 1
# Last N lines
ujust runners logs 1 100
Tokens are automatically generated via GitHub API - no manual copying required!
gh auth login)Each runner has ephemeral storage:
Runners access host container cache (read-only):
If configured, runners use local registry mirror:
| File | Purpose | Location |
|---|---|---|
| Quadlet unit | Service definition | ~/.config/containers/systemd/github-runner-1.container |
| Runner config | Per-runner settings | ~/.config/github-runner/runner-1.env |
# 1. Authenticate GitHub
gh auth login
# 2. Configure runner
ujust runners config https://github.com/myorg/myrepo 1
# 3. Start runner
ujust runners start 1
# 4. Verify in GitHub
# Settings → Actions → Runners
# Add more runners
ujust runners config https://github.com/myorg/myrepo 2
ujust runners config https://github.com/myorg/myrepo 3
# Start all
ujust runners start all
# List pool
ujust runners list
# Option 1: Fast update (brief downtime)
ujust runners stop all
ujust runners update all
ujust runners start all
# Option 2: Rolling update (zero downtime)
ujust runners rolling-update
# Delete runner
ujust runners delete 1
# Reconfigure
ujust runners config https://github.com/myorg/myrepo 1
ujust runners start 1
Runners automatically get these labels:
self-hostedlinuxx64bazzite-aiUse in workflow:
runs-on: [self-hosted, bazzite-ai]
Check:
ujust runners status 1
ujust runners logs 1 50
Common causes:
Fix:
# Re-authenticate
gh auth login
# Reconfigure runner
ujust runners delete 1
ujust runners config https://github.com/owner/repo 1
Symptom: Runner shows "Idle" but jobs queue
Check:
ujust runners logs 1
Common causes:
Check:
systemctl --user status github-runner-1
ujust runners logs 1 100
Common causes:
Optimize:
# Setup local registry mirror
ujust mirror config
# Runners auto-use mirror if configured
mirror (registry caching), pod (build images)gh auth loginUse when the user asks about: