Let’s clear things up.

Connect your GitLab server

1. Open Gloom on a Mac running macOS 14 or later. Gloom lives in the menu bar.
2. In Settings, enter https://gitlab.com or your own HTTPS GitLab server address.
3. Create a GitLab personal access token with read_api permission and an expiry date. Paste the token into Gloom.
4. Choose Test changes, then Apply. Once connected, Gloom keeps the connection section compact. Use Edit connection to change it later.

Gloom reads pipeline information. It does not start, cancel, retry, or modify pipelines. If the token’s permission details are available, Settings warns when it has broader permissions than Gloom needs.

Launch at login is optional. You can enable it at the bottom of Settings; macOS may also require approval in Login Items.

What Gloom keeps an eye on

Settings lists your GitLab membership repositories by default. Use Search and Add to monitor other readable projects, including public repositories; search results are not monitored automatically. Turn reporting off for any repository you want to exclude. Added projects and reporting choices are saved per GitLab server. New membership repositories default to on; removing an added project stops its reporting, including cached rows while paused. Gloom reads each enabled project’s latest pipeline across branches and shows the newest five in the menu.

Expand a pipeline to see stages and jobs, copy failed-job logs, or open the pipeline in GitLab. Widget and Terminal filters select from up to 200 latest enabled project pipelines. They do not retrieve historical pipelines for a branch.

The menu bar status follows the priority you choose in Settings. By default, Gloom prioritizes a failed stage in the newest displayed pipeline. Paused, offline, stale, and refresh-error indicators describe monitoring health separately from the last pipeline result.

Make the status your own

Choose G badges, status symbols, weather icons, or custom emoji. Custom emoji lets you pick your own failed, running, and successful icons. Preview animations in Settings, switch them off individually, and choose a duration from 10 seconds to Always. Gloom respects macOS Reduce Motion.

When the connection needs attention

• Check the HTTPS server address, token expiry, and read_api permission.
• For a private server, connect to your usual VPN and allow local-network access if macOS asks.
• If the server’s certificate is invalid or untrusted, ask your GitLab administrator to fix it. Gloom uses macOS certificate validation.
• Keep Gloom running and check the last refresh time. A saved pipeline result can remain visible when a later refresh fails.

Credentials verified means the token passed the account check. Connected to GitLab requires a successful pipeline refresh. Authentication alone does not prove access to every monitored project.

A little Gloom on your desktop

Add Gloom from the macOS widget gallery. Choose a summary, detail, or overview widget. Keep the main app running so the shared snapshot stays fresh.

Use Private display to hide identifying text and disable pipeline links. This changes what the widget displays; it does not delete the snapshot stored on your Mac. If a widget seems out of date, open Gloom and check its connection and monitoring health.

For the Terminal crowd

The command-line tool comes bundled with Gloom. Settings shows its full path. Installing the optional gloom shortcut lets you use the short name in Terminal; macOS may ask an administrator to approve the shortcut.

gloom status      # Latest shared snapshot
gloom watch       # Watch for changes
gloom logs        # Retrieve failed-job logs
gloom doctor      # Build and connection diagnostics

Use -o json for machine-readable output. Status and watch read Gloom’s local snapshot. Logs connects to your configured GitLab server using the shared credential.

Logs can contain confidential build information. Review clipboard or Terminal output before sharing it. gloom doctor does not print your token, but local paths and environment details may still be identifying.

Trial and subscriptions

At launch, choose $0.99/month or $9.99/year (USD) in Gloom’s subscription settings. Eligible new subscribers receive a 14-day free trial after confirming a plan with Apple. The subscription renews automatically unless canceled; Apple shows the exact local price and terms before confirmation.

Use Restore Purchases with the Apple Account used for the subscription if access is missing. Manage or cancel the subscription through Apple’s subscription settings. If access expires, monitoring stops and your saved GitLab configuration remains available for when you subscribe again.

Still need a hand?

Include your Gloom version, macOS version, what you expected, what happened, and steps to reproduce it. Mention whether you use GitLab.com or a self-hosted server.

Never send an access token. Remove private project details from screenshots and logs.

support@getgloom.dev