Set up runners for MacOS

MacOS Runners allow you to run builds in Pipelines on your own MacOS infrastructure, and you won’t be charged for the build minutes used by your self-hosted runners.

Prerequisites

OpenJDK 11 (11.0.11 or newer) is installed
Git 2.35.0 and above
A 64-Bit MacOS instance with at least 8GB of RAM as a host for the runner.

Using your runner

Deploying multiple runners to a single machine may lead to issues related to resource sharing/usage conflicts due to the shared build environment.

Navigate to the Runners page:
- For Workspace runners, visit Workspace settings > Workspace runners.
- For Repository runners, visit Repository settings > Runners.
Select Add runner.
From the Runner installation dialog, under System and architecture, select MacOS (x86 / Apple Silicon).
Download the tar.gz file provided in the Run step on the Runner installation dialog.
Untar the file to the desired directory, for example: /Users/your_user_name/atlassian_runner
Open Terminal (or shell of your choice), go to the bin directory under your Runner folder, run the command provided in Run step on the Runner installation dialog.

MacOS Runners use Bash to run pipeline steps on your MacOS machine (host device). This allows the runner to execute applications on the host, but does not provide a clean build environment for every step. Any side effects generated by the step (such as, installing any applications, starting a database service, or editing a file outside of the build directory) would potentially affect the next step to be run (including new pipeline runs). To compensate for this, the runner try to empty the build directory empty after each step. It is your responsibility to make sure the scripts you run in each step won’t have a major impact on other steps.

Limitations for MacOS Runner

Memory used by the Runner

It is not possible to completely disable swap memory so processes created by steps that are run on the runner will likely use swap memory. This may result in non-representative build results about memory usage and out-of-memory (OOM) errors. This is may occur when sometimes there will be enough swap memory available and a build may pass, while other times not enough swap is available, which could cause the same build run out-of-memory. Be sure to check for any memory issues due to this limitation.

Shared build environment

Runners use a shell to execute the step scripts, and the host machine will be shared by multiple steps that are scheduled to execute on the runner. If a script installs or changes makes a system-wide change to the runner in step, such as installing a new library, then the change will affect all following steps run on the host machine.

Unsupported features

The following features are not supported by self-hosted runners due to limitations on how they are implemented and security complications:

Bitbucket Pipelines SSH keys
Pipes
Service containers
Custom build images on AWS ECR
Custom Docker in Docker image
Step size — There is no restriction on memory usage for runners.
Overriding the default user

Other limitations and workarounds

Cache

Pre-defined Docker cache is not supported — Docker and the Pipelines pre-defined Docker cache is not supported for MacOS Runners.
Share caches between different OS — We recommend specifying different cache name for different runner types, such as a Linux runner and a MacOS runner. For example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21pipelines: custom: customPipelineWithRunnerAndCache: - step: name: Step 1 runs-on: - 'macos' script: - echo "This step will run on a self hosted runner."; caches: - macos_bundler - step: name: Step 2 script: - echo "This step will run on Atlassian's infrastructure as usual."; caches: - linux_bundler definitions: caches: linux_bundler: vendor/bundle macos_bundler: vendor/bundle
Caches can contain platform-specific files that do not work on other operating systems. Sharing caches between different operation systems might lead to errors, such as when a MacOS runner is trying to use a file that is specifically generated for Linux.
Bloated cache folder — Due to performance implications, we do not clean up the cache folder at the end of step execution. This may lead to the size of cache directories increasing rapidly, particularly for a workspace runner. If this occurs, we recommend creating a scheduled task to clean up cache folders on a regular basis. You can refer to the following documentation created by Apple to see how to setup a scheduled task with Launchd: Scheduling Timed Jobs.
Be aware that we don’t restrict where your cache folder is located, so you can store the cache in any directory of the device. Be mindful about any technical implications of where your cache is defined and make sure your host machine is recoverable.

Git LFS

In order to use Git LFS, you need to install Git LFS on your hosted machine. If you use Homebrew, you can install Git LFS with the following terminal command:

brew install git-lfs

SSH Keys

You'll want to set up an SSH key in Bitbucket Pipelines if:

your build needs to authenticate with Bitbucket or other hosting services to fetch private dependencies.
your deployment needs to authenticate with a remote host or service before uploading artifacts.
you want builds to use tools such as SSH, SFTP, or SCP.

For security reasons, a runner will not add your SSH keys to the build environment automatically. If required, SSH keys can be passed to a runner using a secure variable.

There are security risks associated with passing private SSH keys as repository variables:

Repository variables are copied to child processes that your pipeline builds may spawn.
Secured variables can be retrieved by all users with write access to a repository.

We recommend that you never reuse an SSH key as a repository variable. Generate a new SSH key-pair for Pipelines, so the key can be disabled if it is compromised. It is possible to use deployment variables, which you can use with deployment permissions to control access. For details, see: Variables and secrets — Deployment variables.

To add your SSH key using a secure repository variable with OpenSSH:

In a terminal, generate a new SSH key, such as:
1ssh-keygen -t rsa -b 4096 -N '' -f ~/.ssh/my_ssh_key
Encode the private key to base64. Pipelines does not currently support line breaks in environment variables. For example:
1base64 -w 0 ~/.ssh/my_ssh_key
Add the encoded key as a secure variable. Copy the encoded key from the terminal and add it as a secured Bitbucket Pipelines environment variable to the repository:
1. In the Bitbucket repository, select Repository settings > Repository variables.
2. Copy the base64-encoded private key from the terminal.
3. Paste the encoded key as the value for an environment variable. Make sure to check Secured.
Install the public key on a remote host. You must install the public key on the remote host before Pipelines can authenticate with that host. If you want your Pipelines builds to be able to access other Bitbucket repositories, you need to add the public key to that repository.
To copy the public key to the remote host using SSH, use the ssh-copy-id command. This command appends the key to the ~/.ssh/authorized_keys file on the remote host:
1ssh-copy-id -i my_ssh_key <username>@<remote_host>
Where <username> is a user on the remote host.
To test the SSH access to the server:
1ssh -i ~/.ssh/my_ssh_key user@host
Get the host keys and add them to ~/.ssh/known_hosts file in the host virtual machine (VM).
The known_hosts file contains the DSA host keys of SSH servers accessed by the user. It's important to verify that you're connecting to the correct remote host.
1. Get the DSA host keys of any remote servers. You can do this by executing the following command:
  1ssh-keyscan -t rsa server.example.com
2. Add those keys to the ~/.ssh/known_hosts file in the host VM. You can remove any unrelated lines.
Add and decode the SSH key in the bitbucket-pipelines.yml file. For example:
1 2 3 4 5 6 7pipelines: default: - step: runs-on: self.hosted script: - (umask 077 ; echo $MY_SSH_KEY | base64 --decode > ./id_rsa) - ssh -i ./id_rsa <user>@<host> 'echo "connected to `host` as $USER"'

In the script provided above, we use ./id_rsa instead of ~/.ssh/another_private_key. This ensures that the runner will monitor the file generated in the runner build folder and will attempt to remove it at the end of the step. Any files that are created outside of the runner build folder will not be removed and the runner will leave private keys in ~/.ssh, which will increase the chance of the key being exploited.

There is still a chance that we will not be able to clean up the build folder. We suggest you update the SSH key-pair used in the step on a regular basis to reduce the chance of any of your data being compromised.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community