Bitrise Desktop App for macOS

The Bitrise Desktop App is a native macOS menu bar app that shows the live status of your builds for the branch you're working on, so you don't need to open a browser tab to check build status.

note

The Bitrise Desktop App is macOS only.

Installing the app

The Bitrise Desktop App requires macOS 14.6 or later and a Bitrise account with access to at least one workspace and project. If you want to track a local folder, you also need a local checkout of the repository.

1. Download the Bitrise.dmg file from GitHub.
2. Open the .dmg and drag Bitrise onto the Applications folder.
3. Launch Bitrise from Applications.

The app appears as an icon in the menu bar on the top of your screen. On first launch, it shows an unconfigured state until you sign in.

Launching at login

In Settings, in the General pane, turn on Launch at login to have the app start automatically each time you log in to your Mac, so build status is in the menu bar without opening the app manually.

Signing in

1. Click the Bitrise icon in the menu bar.
2. Click Connect to Bitrise. The app opens your browser to sign in.
3. Complete sign-in in the browser, then return to the app.

After sign-in, the app stores your access token in the macOS Keychain and refreshes it automatically. Your signed-in handle appears in the build list header and in Settings.

Choosing a workspace

The selected workspace scopes everything the app shows, including builds, filters, and local-folder matching.

• If you belong to one workspace, it's selected automatically.
• If you belong to several, pick one from the workspace picker.
• If you belong to none, the app points you to the Bitrise web UI to get access.

You can switch workspace later from Settings, in the Account pane.

Adding projects to watch

The build list starts empty. You populate it by subscribing to one or more projects in Settings, in the Projects pane. There are two ways to add a project:

• Subscribing to a project directly: This is a project-health watch. Use it to keep an eye on a project regardless of what you have checked out locally, for example, to confirm main stays green.
• Tracking a local folder: The app matches each repository to its Bitrise project by the git remote URL, so you don't need to pick the project manually. It then tracks builds for the branch you currently have checked out, and stays in sync as you switch branches locally.

Subscribing directly

1. Open Settings and go to the Projects pane.
2. Choose a project from your workspace to watch.

Tracking a local folder

1. In the Projects pane, choose to add a local folder and browse to it.
2. The app scans the folder and its subfolders for git repositories and lists what it finds.
3. Select the repositories you want to track.

note

A branch with no builds in Bitrise shows an empty list. If you switch to a new branch that hasn't run any builds yet, that's expected.

Setting filters and notifications

Each project you watch has its own settings, edited in its detail view in the Projects pane.

• Branches: Choose which branches a project tracks. For local folders, this stays in sync with your checkout automatically.
• Notifications: set each project to off, failures only, or every completion. A global Allow notifications switch in the Notifications pane turns all banners on or off.

Grouping the build list

In Settings, in the Builds pane, choose how the build list is organized:

• By project: group builds under their project, one section per project.
• By date: list every build newest-first across all projects, each one labeled with its project.

A project can be dual-tracked: watched both because you subscribed to it directly and because you're tracking a local folder that matches the same repository. For dual-tracked projects, choose how to display them:

• Separate lists per source: show two sections for the project, one per source, each labeled with an icon showing where it came from.
• Merged into one list: combine builds from both sources into a single list for that project.

Reading build status

The menu bar icon mirrors the most recently started build across the projects you watch:

• Passed: the most recent build passed.
• Failed: the most recent build failed.
• Running: a build is in progress.
• Aborted: the most recent build was aborted.

Click the icon to open the build list. Each build appears as a card showing its status and commit message, the branch or tag, the Workflow or Pipeline name, and the start time, duration, and build number. From a card, you can open the build, the pull request, or the commit on Bitrise in one click.

For the full list of build statuses Bitrise tracks, see Build statuses.

Keeping the app updated

The app checks for newer releases periodically, and on demand from Settings, in the About pane, using Check Now.

When an update is available, you can download the new .dmg. Install it by dragging the app into Applications, the same way as the first install.

Troubleshooting

What you see	What it means and what to do
Empty build list on a branch	That branch has no builds in Bitrise. Switch to a branch with build history, or trigger a build.
Project not found for a folder	The folder's git remote doesn't match a project in the selected workspace. Confirm the remote and the workspace.
Remote is outside this workspace	The repository belongs to a different workspace. Switch workspace in the Account pane.
Detached HEAD or no remote	The app can't determine a branch to track. Check out a branch with an upstream remote.
Sign-in error	Authentication failed or expired. Sign in again from the menu bar.