Rover

A small app that watches your GitLab merge requests and fires a native notification the moment one of their pipelines passes, fails, or needs manual intervention.

Each watched MR gets its own emoji + title so you can tell at a glance which one a notification belongs to.

What you'll need

• macOS, Windows, or Linux — Rover uses cross-platform Electron APIs for notifications and secure token storage
• Node 20+ (npm comes with it)
• A GitLab access token with the two read permissions described below

Setup

git clone <this-repo>
cd rover
npm install
npm run dev

On first launch the app opens an onboarding window that walks you through:

1. Picking your GitLab host (gitlab.com or self-hosted)
2. Pasting your access token (encrypted at rest using your OS's secure storage — Keychain on macOS, DPAPI on Windows, libsecret on Linux)
3. Testing the connection
4. Choosing how often to poll (default: 60 seconds)

Creating a GitLab token

The app needs exactly two read permissions:

• READ on CI/CD Pipeline — for polling pipeline status
• READ on Repository Merge Request — for reading the MR's title when you add it

That's it. No write access, no other endpoints.

Pick the narrowest token type that works for you:

1. Project access token with a custom role (tightest — can only see one project, only those two abilities) Project → Settings → Access tokens → Add new token. Assign a custom role that grants only Read CI/CD Pipeline + Read Repository Merge Request, and scope api. Use this if all the MRs you want to watch live in one project.
2. Group access token (can see one group + its subgroups) Group → Settings → Access tokens → Add new token with the same custom role. Use this if your watched MRs span multiple projects in the same group.
3. Personal access token with read_api (broadest — sees everything you can see across the whole instance) https://<host>/-/user_settings/personal_access_tokens. Use only when 1 and 2 aren't possible.

Why does this matter? A personal read_api token can read every project, snippet, registry, and issue you can see. A project token with the two-permission custom role can read only pipelines and MRs in that one project. If your machine is compromised, the smaller token has a much smaller blast radius.

Adding an MR to watch

1. Click + Watch a new MR
2. Paste the full MR URL (e.g. https://gitlab.com/group/project/-/merge_requests/1234)
3. Pick an emoji from the grid if you choose
4. Optionally override the display title (defaults to the MR's title from GitLab)
5. Watch this MR

The app will start polling immediately.

Notification format

• Title: {your emoji} {your title} — e.g. 🔥 Auth refactor
• Body: ✅, ❌, ⏸ or 🎉 + short commit SHA where relevant
• Click: opens the pipeline / MR page in your default browser

Note: macOS, Windows, and Linux don't let third-party apps customise notification background colours. The emoji in the title and the icons in the body do the at-a-glance differentiation; the popover UI also shows a coloured status dot per MR.

Building a packaged binary

# macOS
npm run build:mac    # → .app and .dmg in dist/

# Windows
npm run build:win    # → .exe / .msi in dist/

# Linux
npm run build:linux  # → .AppImage / .deb / .snap in dist/

Without a signing identity the first launch may show a "publisher unverified" warning on each platform — bypass it once and you're set.

Where data lives

Platform	Token / config / watched MRs
macOS	~/Library/Application Support/rover/
Windows	%APPDATA%\rover\
Linux	~/.config/rover/

The token file is encrypted; the config and watched-MR JSON are plaintext (no secrets). To wipe everything, delete that folder.

Troubleshooting

"OS-level encryption is not available" — Rover refuses to store the token in plaintext. On Linux you need libsecret (gnome-keyring or kwallet) installed. On macOS you need to be in a logged-in desktop session (won't work over SSH). On Windows DPAPI is always available.

No notifications appear — check your OS notification settings for Rover and make sure it's allowed to send notifications. The OS asks for permission the first time but it's easy to miss the prompt.

mrs:add says the host doesn't match — the URL host has to match the configured host exactly. Update Settings → GitLab host to match.

Limits / out of scope

• Single GitLab host per install (multi-host is a planned follow-up)
• GitLab only (GitHub support is a planned follow-up)
• No code signing — clone & build per machine
• Currently developed and tested on macOS only; Windows and Linux builds should work but may have small platform-specific quirks