ARC Runner Manager

A Claude Code plugin for managing and troubleshooting GitHub Actions Runner Controller (ARC) runners on Kubernetes clusters.

Overview

ARC Runner Manager provides comprehensive tools for deploying, monitoring, and maintaining GitHub Actions Runner Controller (ARC) infrastructure on any Kubernetes cluster (microk8s, GKE, EKS, AKS, and more).

Key Features

• Deploy runners — Initialize new ARC runners with GitHub App credentials and Helm
• Diagnose issues — Troubleshoot connection failures, version mismatches, and pod problems
• Scale runners — Adjust min/max runner counts and resource configurations
• Manage credentials — Rotate GitHub App credentials and update authentication
• Production validation — Pre-deployment safety checks and best practices for production environments
• Version management — Handle upgrades, rollbacks, and version alignment between controller and runners

Installation

Add the marketplace:

/plugin marketplace add full-stack-biz/claude-arc-runner-manager

Install the plugin:

/plugin install arc-runner-manager@full-stack-biz

Quick Start

Invoke the skill in Claude Code:

/arc-runner-manager

The skill provides three primary workflows:

1. Troubleshooting Workflow

Diagnose unhealthy runners or connection failures. Includes step-by-step debugging for:

• Runner status and pod health checks
• Controller and listener log analysis
• Root cause identification (auth errors, version mismatches, resource constraints)
• Remediation steps from the troubleshooting guide

2. Deployment Workflow

Deploy new ARC runners or reinstall existing ones. Covers:

• Prerequisite verification (Kubernetes, Helm, GitHub App setup)
• Secret creation with GitHub App credentials
• Helm-based runner deployment
• Verification in both Kubernetes and GitHub

3. Configuration Workflow

Adjust runner settings, scaling, and Helm values. Includes:

• Viewing current configurations
• Modifying runner scaling (minRunners/maxRunners)
• Updating labels, resource constraints, and other settings
• Applying changes via Helm upgrade

Documentation

The plugin includes comprehensive reference guides:

• Deployment Guide — Complete deployment procedures, credential management, version upgrades, and safe upgrade procedures for production
• Troubleshooting Guide — Common errors, diagnosis steps, and remediation for connection failures, version mismatches, pod crashes, and listener issues
• Configuration Reference — All autoscalingrunnersets fields and Helm chart options
• Production Validation — Pre-deployment safety checks, validation scripts, and production-ready checklist

Architecture

The plugin is organized as follows:

.claude-plugin/
├── plugin.json                  # Plugin manifest
├── marketplace.json             # Marketplace registration
└── skills/arc-runner-manager/
    ├── SKILL.md                 # Main skill with workflows
    └── references/              # Detailed guides
        ├── deployment-guide.md
        ├── troubleshooting-guide.md
        ├── configuration-reference.md
        └── production-validation.md

Important Notes

Safety First

• Version alignment — Controller (arc-systems) and runner (arc-runners) chart versions must match to avoid silent failures
• Credential security — GitHub App private keys are stored only in Kubernetes secrets; never logged or exposed
• Production validation — Always use the production validation checklist before deploying to production
• Backup procedures — Always backup Helm values before major operations: helm get values <release> -n arc-runners > backup.yaml

Tool Access

The skill uses:

• Bash — kubectl, helm, and microk8s commands (read-only by default; write operations require explicit user approval)
• Read — View manifests, configurations, and logs
• Edit/Write — Modify configurations (requires confirmation for production changes)

Requirements

• Kubernetes cluster with kubectl access
• Helm 3+ installed
• GitHub App with proper permissions:
  • administration:read
  • actions:read
  • runners:write
• ARC Controller running in the cluster (arc-systems namespace)

Author

Full-stack.biz OU — https://github.com/full-stack-biz

License

MIT

Support

For issues, documentation, or contributions, visit the repository.