Skip to content

Getting Started

BenKoncsik edited this page May 4, 2026 · 1 revision

Getting Started

What GitRunnerManager Does

GitRunnerManager is a lightweight menu bar (macOS) or system tray (cross-platform) application that manages local GitHub Actions self-hosted runners. Instead of manually starting and stopping the runner process in a terminal, GitRunnerManager provides:

  • A visual status indicator in the menu bar / system tray
  • One-click start, stop, and restart controls
  • Automatic mode that reacts to network and battery conditions
  • Resource usage monitoring (CPU and memory)
  • Activity detection (idle, busy, stopping)
  • Launch-at-login management

Requirements

SwiftUI (Native macOS)

  • macOS 14.0 or later
  • Xcode or Swift Package Manager for building from source
  • A configured GitHub Actions self-hosted runner directory

Avalonia (Cross-Platform)

  • .NET 10 SDK for building from source
  • macOS, Windows, or Linux
  • A configured GitHub Actions self-hosted runner directory

Basic Setup Flow

  1. Install or build the application for your platform. See Installation for details.
  2. Configure the runner directory -- point the app to the directory containing your GitHub Actions runner (the directory with run.sh / run.cmd).
  3. Choose a control mode -- select between Automatic, Force Running, or Force Stopped. See Usage for details.
  4. (Optional) Enable launch at login -- the app will start automatically when you log in.
  5. (Optional) Configure automation policies -- enable battery-aware or network-aware stopping in Settings.

Control Modes Overview

GitRunnerManager offers three control modes:

Mode Behavior
Automatic The app decides whether to start or stop the runner based on network conditions and battery state. See Automation for details.
Force Running The runner is started and kept running regardless of network or battery state.
Force Stopped The runner is stopped and will not be started automatically.

In Automatic mode, the reconciliation logic evaluates:

  1. Battery state -- if "Stop on Battery" is enabled and the system is on battery, the runner is stopped.
  2. Network state -- unmetered connections trigger a start; expensive/metered connections trigger a stop; offline triggers a stop.

Next Steps

  • Read the Installation page for build and install instructions
  • See Usage for a detailed guide to the menu bar controls
  • Configure your preferences in Settings

Clone this wiki locally