A system tray application that monitors GitHub Actions build status for your repositories.
- Real-time monitoring of GitHub Actions workflow status
- System tray icon with color-coded status indicators:
- 🟢 Green: All builds passing
- 🔴 Red: One or more builds failing
- 🟡 Yellow: Builds in progress
- ⚪ Gray: Unknown/no builds
- Click on repository names to open build details in browser
- Add/remove repositories from the system tray menu
- No GitHub token required for public repositories
- Configurable update interval
- Clone this repository:
git clone https://github.com/yourusername/gh-status.git
cd gh-status- Install dependencies:
pip install -r requirements.txt- (Optional) Create your configuration file:
cp config.yaml.example config.yaml- (Optional) Set up auto-start at login:
python install_startup.pyRun the monitor:
python gh_status_monitor.pyThe app will create a default config with some popular repos if none exists.
- Right-click the system tray icon
- Select "Add Repository..."
- Enter repository in format:
owner/repo(e.g.,facebook/react)
# Add single repository
python add_repos.py facebook/react
# Add multiple repositories
python add_repos.py vercel/next.js microsoft/vscode torvalds/linux
# List all configured repositories
python add_repos.py --listrepositories:
- owner: facebook
repo: react
- owner: vercel
repo: next.jsOnly needed for:
- Private repositories
- Increasing API rate limits (60/hour → 5000/hour)
Create a token at https://github.com/settings/tokens with:
public_reposcope for public repos onlyreposcope for private repos
Run the monitor:
python gh_status_monitor.pyOr make it executable:
chmod +x gh_status_monitor.py
./gh_status_monitor.pyThe application will:
- Start in your system tray
- Check build status every 5 minutes (configurable)
- Update the tray icon based on overall status
- Right-click the icon to see individual repository statuses
- Repository names: Click to open the latest workflow run in your browser
- Refresh: Manually update all repository statuses
- Quit: Exit the application
Use the provided installer for your platform:
# Interactive installer (works on macOS, Linux, Windows)
python install_startup.py
# Or platform-specific:
# macOS only
python install_launch_agent.pyThe installer will:
- macOS: Create a LaunchAgent that starts at login
- Linux: Create a systemd user service
- Windows: Add to startup folder with silent execution
- Run
python install_launch_agent.py --install - Or manually: System Preferences → Users & Groups → Login Items → Add script
- Run
python install_startup.pyand choose option 1 - Or manually: Add to your desktop environment's startup applications
- Run
python install_startup.pyand choose option 1 - Or manually: Copy the generated .vbs file to your Startup folder
- Python 3.6+
- System with system tray support (Windows, macOS, Linux with desktop environment)
- No icon appears: Ensure your system supports system tray icons
- Authentication errors: Verify your GitHub token has the correct permissions
- No status updates: Check your internet connection and GitHub API limits
MIT License - see LICENSE file for details