FAQ

FAQ

General Questions

What does GitRunnerManager do?

GitRunnerManager is a menu bar / tray application that manages local GitHub Actions self-hosted runners. It provides visual status indicators, one-click controls, automatic mode based on network and battery conditions, and resource monitoring.

What is the difference between the SwiftUI and Avalonia implementations?

Aspect	SwiftUI	Avalonia
Platform	macOS only	macOS, Windows, Linux
Focus	Lightweight native macOS experience	Full cross-platform feature set
Runner profiles	Single runner	Multiple runner profiles
GitHub integration	Not implemented	Full GitHub Actions dashboard
Runner setup wizard	Not implemented	5-step guided wizard
Runner binary updates	Not implemented	Automatic update service

Which implementation should I use?

• If you are on macOS and want a lightweight native app, use the SwiftUI implementation.
• If you need cross-platform support or advanced features like multi-runner management and GitHub Actions integration, use the Avalonia implementation.

Runner Safety

Will stopping the runner interrupt a running job?

When you manually click Stop, the runner is terminated immediately. In Automatic mode, the Avalonia implementation includes job safety: if a job is actively running (detected by Runner.Worker process presence), battery-aware and metered-network-aware stops are skipped to prevent interrupting in-progress work.

The SwiftUI implementation does not include job safety checks in automatic stops.

Is it safe to force quit the runner?

The stop sequence uses a graded shutdown (SIGINT --> SIGTERM --> SIGKILL) to allow graceful cleanup first. Force kill (SIGKILL) is only used as a last resort after the runner fails to respond to earlier signals. However, abrupt termination may leave the runner in an inconsistent state on the GitHub side, requiring manual cleanup.

What happens if the app crashes while the runner is running?

The runner process continues running independently of the app. The app does not manage the runner's lifecycle outside of explicit start/stop commands. If the app crashes, you will need to stop the runner manually (via the runner directory or process manager).

Multiple Runners

Can I manage multiple runners?

• SwiftUI: No, the SwiftUI implementation supports a single runner directory.
• Avalonia: Yes, the Avalonia implementation supports multiple runner profiles, each with its own directory, settings, and independent control.

How do I switch between runners?

• SwiftUI: Change the runner directory in Settings under the Runner section.
• Avalonia: Select the desired runner profile from the profile list in the tray menu or Settings.

Resource Monitoring

How should I interpret CPU and memory usage?

CPU and memory values are aggregated across all runner-related processes (Runner.Listener and Runner.Worker).

• CPU%: Percentage of total CPU used by runner processes. A busy job typically shows elevated CPU usage.
• Memory (RSS): Resident Set Size in MB. This is the actual physical memory used by runner processes.

Values near zero indicate the runner is idle (listening for jobs). Higher values indicate active job execution.

Why does CPU usage sometimes spike?

CPU spikes are normal when:

• A new job is starting
• The runner is processing a job with computational tasks
• The runner is updating itself

Spikes should return to near-zero when the runner returns to idle.

Network and Battery Behavior

What happens when the network goes offline?

In Automatic mode, the runner is stopped when the network becomes offline. When the network returns to an unmetered state, the runner is automatically restarted.

What is considered a "metered" or "expensive" connection?

• macOS (SwiftUI): Cellular connections or personal hotspots detected via NWPathMonitor.
• Avalonia (macOS): Determined via scutil --nwi output.
• Avalonia (generic): Determined via NetworkInterface.GetAllNetworkInterfaces().

When on a metered connection, the runner is stopped in Automatic mode to avoid consuming mobile data.

What happens when I switch to battery power?

If the "Stop on Battery" setting is enabled, the runner is stopped when the system switches to battery power. When AC power is restored, the runner is automatically restarted (in Automatic mode).

Can I prevent the runner from stopping on battery?

Yes. Disable the "Stop on Battery" toggle in Settings under General. Alternatively, switch to Force Running mode to keep the runner running regardless of battery state.

Next Steps

• See Troubleshooting for solutions to common problems
• See Automation for details on automatic mode behavior
• See Settings for configuration options