Standfast

Product Introduction

1. Definition: Standfast is a free, open-source macOS menu bar application designed for monitoring and managing self-hosted GitHub Actions runners. It falls into the technical categories of DevOps tooling, infrastructure monitoring, and CI/CD (Continuous Integration/Continuous Deployment) management software.
2. Core Value Proposition: Standfast exists to solve the critical visibility gap between a runner's local process status and its actual availability on the GitHub Actions platform. Its core value is providing real-time, dual-source health monitoring to prevent silent failures where a runner process is "up" but GitHub cannot assign it work, thereby eliminating build queue delays and improving CI/CD reliability.

Main Features

1. Dual-Source Runner Health Monitoring: Standfast performs independent checks for each runner. It queries the local macOS launchd service manager to verify the runner process is alive and simultaneously polls the GitHub Actions API to confirm the runner is registered, connected, and in an "Idle" or "Active" state. This architecture ensures the two statuses are never conflated, providing a true picture of runner health.
2. Unified Menu Bar Interface with Granular Detail: The app aggregates the status of all monitored runners into a single, glanceable menu bar icon. Clicking the icon opens a detailed menu with one row per runner, showing its combined state (e.g., "Ready," "Disconnected," "Running"). A dedicated window offers a comprehensive overview, including per-runner job details, disk usage analytics, version checks, and logs.
3. Automated Discovery and Non-Intrusive Management: Standfast automatically discovers runners installed as macOS LaunchAgent services by parsing their .plist files and companion .runner configuration files. It provides management actions (Start, Stop, Restart) for these service-based runners directly from its UI. It can also monitor manually-started runners and GitLab runners via user-added paths and tokens, all without requiring sudo privileges.
4. Proactive Alerts and System Integration: The app offers configurable notifications for key events like job failures, runner disconnections, or unexpected stops. It can optionally prevent system idle sleep while a job is running (though not on a closed laptop lid). It also provides warnings for system thermal throttling and checks runner version against the latest actions/runner release to preempt obsolescence issues.

Problems Solved

1. Pain Point: The "silent offline" runner problem. A common failure mode where a self-hosted GitHub Actions runner process (./runsvc.sh) continues running locally, but its registration with GitHub has lapsed or its connection has dropped. Traditional checks (svc.sh status, Activity Monitor) show the runner as healthy, while jobs queue indefinitely on GitHub, causing debugging delays and pipeline failures.
2. Target Audience: Developers, DevOps engineers, and platform teams who manage macOS-based CI/CD infrastructure. This includes individuals or small teams using a Mac mini as a build server, open-source maintainers with self-hosted runners, and organizations with fleets of macOS runners for building and testing iOS, macOS, or cross-platform applications.
3. Use Cases:
   • Rapid Triage: Immediately diagnosing why a GitHub Actions job is stuck in "queued" status by checking if the designated runner is "Disconnected" in Standfast.
   • Proactive Maintenance: Receiving a notification when a runner automatically stops after a job, or when its version is nearing the minimum required by GitHub.
   • Resource Cleanup: Using the integrated disk usage breakdown to identify and clean up old tool caches and workflow artifacts from runner directories.
   • Fleet Overview: Getting a single-pane-of-glass view of the status (Ready, Running, Stopped) for all self-hosted runners on a given Mac host.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros:
     • Precision Monitoring: The dual-check architecture is its defining strength, accurately distinguishing between a local process failure and a GitHub connectivity/registration issue.
     • Zero Configuration for Standard Setups: Automatically discovers service-based GitHub Actions runners with no manual setup.
     • Privacy-Focused: No telemetry, analytics, or data exfiltration. Credentials are stored locally in the macOS Keychain.
     • Native and Lightweight: A signed, notarized native macOS app that runs efficiently from the menu bar without a background daemon.
   • Cons:
     • Platform Lock-in: Exclusively for macOS 14+. Cannot monitor runners hosted on Linux or Windows servers.
     • No Runner Provisioning: It is a monitoring and control tool only; it cannot register new runners or modify runner labels.
     • Limited Enterprise Support: Does not support GitHub Enterprise Server instances, as it only communicates with github.com.
     • Passive for Manual Runners: Can monitor but cannot start/stop runners launched manually via ./run.sh.

2. Key Alternatives & Differentiation:

   • Native GitHub Actions UI / gh runner CLI: The standard method involves checking the "Runners" tab in repository/organization settings or using gh runner list. Differentiation: Standfast provides real-time, centralized monitoring without switching contexts or running CLI commands, and crucially, correlates the GitHub status with the local process state.
   • Generic Server Monitoring (e.g., Nagios, Prometheus): These tools can check if the runner process is running via custom scripts. Differentiation: Standfast has built-in, deep integration with the GitHub Actions API to check runner registration and job queue status, which generic monitors lack. It also offers native macOS management actions.
   • Commercial CI/CD Monitoring Platforms: Tools like Datadog CI Visibility or GitLab's built-in monitoring. Differentiation: Standfast is a free, specialized, and lightweight tool focused solely on the health of self-hosted runners. It requires no cloud service, complex agent installation, or subscription fee.

Frequently Asked Questions (FAQ)

1. Does Standfast work with GitHub Enterprise Server? No, Standfast does not support GitHub Enterprise Server. It is designed to work with GitHub Actions on github.com and sends all API requests to that domain. Runners registered on an Enterprise Server instance will appear as "GitHub not answering."
2. Can Standfast start/stop runners on a remote Mac or a Linux server? No. Standfast is a local macOS application. It can only monitor and manage runners on the Mac where it is installed. It uses the local launchctl command and filesystem access to interact with runners.
3. Is a GitHub Personal Access Token (PAT) required to use Standfast? A token is not strictly required for basic status checks if you have authenticated the GitHub CLI (gh) on your system. However, to see detailed queued job information for repository runners, you must provide a GitHub PAT with appropriate repo or organization permissions in Standfast's Settings.
4. How does Standfast impact the performance of my runners? Standfast has minimal performance impact. It makes lightweight, periodic API calls to GitHub (respecting rate limits) and reads local log files and service status. It does not run any code within the runner's job execution environment or consume significant CPU/memory.
5. Can I use Standfast to monitor runners for a GitHub organization? Yes. Standfast works with runners at the repository, organization, and enterprise levels. You need to provide a GitHub token with the appropriate scope (admin:org for organization runners, manage_runners:enterprise for enterprise runners) to allow Standfast to query their status.