A lightweight macOS menu bar app that monitors GitHub Actions CI status across your repositories at a glance.
Octocheck sits in your menu bar and continuously polls GitHub Actions for the latest workflow status on your selected repositories. The menu bar icon reflects the aggregate state — orange while any build is running, red if anything fails, green when everything passes.
Click the icon to see a breakdown of each repo and branch, open any repo's Actions page in your browser, or trigger a manual refresh.
- Colored status icon — green/red/orange/gray menu bar icon at a glance
- Multi-branch tracking — monitor multiple branches per repository
- Per-repo workflow name — configure which workflow to track per repo (default: "CI")
- Aggregate status icon — one look tells you if all CI is green
- Per-repo breakdown — see individual status, branch, and last update time
- Configurable polling — 1, 2, 5, 10, 15, or 30-minute intervals (default 5 min)
- Secure auth — GitHub PAT stored locally with restricted file permissions
- Desktop notifications — get notified when a repo's status changes (e.g. passing → failing)
- Network-aware — pauses polling when offline, resumes automatically
- Launch at Login — optional auto-start via macOS ServiceManagement
- No Dock icon — runs purely as a menu bar utility
- macOS 13 (Ventura) or later
- A GitHub Fine-grained Personal Access Token with Actions read-only permission
Download the latest Octocheck.zip from the Releases page, unzip it, and double-click Octocheck.app to run.
Note: macOS may show a security prompt since the app is unsigned. Right-click the app → Open, or go to System Settings → Privacy & Security and click Open Anyway.
If you prefer to build it yourself:
git clone https://github.com/warmwind/octocheck.git
cd octocheck
chmod +x build-app.sh
./build-app.sh
open Octocheck.appThis builds via Swift Package Manager and wraps the binary in a proper .app bundle.
- Click the Octocheck icon in your menu bar → Settings
- Go to the Authentication tab and enter your GitHub PAT
- Go to the Repositories tab, load your repos, and add the ones you want to monitor
- Expand a repo to add branches and configure the workflow name to track
- Statuses start polling immediately
Once running, Octocheck lives in your menu bar. Click the icon to open the popover:
- Each row shows a repo's name, branch, current CI status, and a colored indicator
- Click the arrow icon on any row to open that repo's GitHub Actions page in your browser
- Click Refresh Now to fetch statuses immediately instead of waiting for the next poll
- Click Quit to exit the app
- Open Settings → Repositories
- Click Load Your Repositories to fetch your GitHub repos
- Click the + icon to add a repo (its default branch is added automatically)
- Expand a repo to add more branches or change the tracked workflow name
- Click the - icon to remove a repo or branch
Open Settings → General to:
- Polling interval — how often Octocheck checks GitHub (1 min to 30 min)
- Launch at Login — start Octocheck automatically when you log in
- Notifications — toggle desktop notifications for status changes (e.g. a build breaks or recovers)
- Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
- Click Generate new token
- Set a token name and expiration
- Under Repository access, select the repos you want to monitor (or All repositories)
- Under Permissions → Repository permissions, set Actions to Read-only
- Click Generate token, copy it, and paste it into Settings → Authentication in Octocheck
| Icon | State | Meaning |
|---|---|---|
checkmark.circle |
Passing | Latest workflow run succeeded |
xmark.circle |
Failing | Latest workflow run failed or timed out |
arrow.triangle.2.circlepath |
Running | Workflow is in progress, queued, or pending |
questionmark.circle |
Unknown | No matching workflow runs found |
Aggregate logic: any running → orange; else any failure → red; else all success → green.
Octocheck calls GET /repos/{owner}/{repo}/actions/runs?branch={branch}&per_page=20 per repo×branch, filtered by the configured workflow name. With 10 repo×branch combinations at a 5-minute interval, that's ~120 requests/hour — well within GitHub's 5,000 req/hr limit.
MIT