- Change the system shell to Bash
- Install Homebrew, rbenv, and GitLab Runner
- Configure rbenv and install Ruby
- Install Xcode
To run a CI/CD job on a macOS runner, complete the following steps in order.
When you’re done, GitLab Runner will be running on a macOS machine and an individual runner will be ready to process jobs.
- Change the system shell to Bash.
- Install Homebrew, rbenv, and GitLab Runner.
- Configure rbenv and install Ruby.
- Install Xcode.
- Register a runner.
- Configure CI/CD.
Before you begin:
- Install a recent version of macOS. This guide was developed on 11.4.
- Ensure you have terminal or SSH access to the machine.
Newer versions of macOS ship with Zsh as the default shell. You must change it to Bash.
Connect to your machine and determine the default shell:
If the result is not
/bin/bash, change the shell by running:
chsh -s /bin/bash
- Enter your password.
- Restart your terminal or reconnect by using SSH.
echo $SHELLagain. The result should be
The runner needs certain environment options to connect to the machine and run a job.
Install the Homebrew package manager:
/bin/bash -c "$(curl "https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh")"
rbenv, which is a Ruby version manager, and GitLab Runner:
brew install rbenv gitlab-runner brew services start gitlab-runner
Now configure rbenv and install Ruby.
Add rbenv to the Bash environment:
echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile source ~/.bash_profile
Install Ruby 2.74 and set it as the machine’s global default:
rbenv install 2.7.4 rbenv global 2.7.4
Now install and configure Xcode.
Go to one of these locations and install Xcode:
Agree to the license and install the recommended additional components. You can do this by opening Xcode and following the prompts, or by running the following command in the terminal:
sudo xcodebuild -runFirstLaunch
Update the active developer directory so that Xcode loads the proper command line tools during your build:
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
Now create and register a project runner.
When you create and register the runner:
- In GitLab, add the tag
macosto ensure macOS jobs run on this macOS machine.
- In the command-line, select
shellas the executor.
After you register the runner, a success message displays in the command-line:
> Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
To view the runner:
- On the left sidebar, select Search or go to and find your project or group.
- Select Settings > CI/CD.
- Expand Runners.
In your GitLab project, configure CI/CD and start a build. You can use this sample
Notice the tags match the tags you used to register the runner.
stages: - build - test variables: LANG: "en_US.UTF-8" before_script: - gem install bundler - bundle install - gem install cocoapods - pod install build: stage: build script: - bundle exec fastlane build tags: - macos test: stage: test script: - bundle exec fastlane test tags: - macos
The macOS runner should now build your project.