Skip to main content

Bitrise for Mac

Bitrise for Mac 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

Bitrise for Mac is macOS only.

Installing the appClick to copy link​

Bitrise for Mac 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.

Signing inClick to copy link​

  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 workspaceClick to copy link​

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 watchClick to copy link​

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.
  1. Open Settings and go to the Projects pane.
  2. Choose a project from your workspace to watch.
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 notificationsClick to copy link​

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

  • Branch filter: Choose which branches a project tracks. For local folders, this stays in sync with your checkout automatically.
  • Show only builds since the last push: for local folders, hide builds that started before your most recent push, so old runs on the same branch don't clutter the list.
  • Notification mode: 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.

Reading build statusClick to copy link​

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 updatedClick to copy link​

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.

TroubleshootingClick to copy link​

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