GitHub recommends using self-hosted runners with private repositories for enhanced security.
Configuring a GitHub Actions runner on a Mac mini for enhanced CI/CD
- mac
- m1
- github-actions
GitHub Actions is a CI/CD platform that allows users to automate their software development workflows, connected to a Github organization or repository. While GitHub offers online runners with a pay-as-you-go model, self-hosted runners grant increased control over your CI/CD setup and enhanced customization. This is because you manage the runners yourself, rather than relying on GitHub’s infrastructure. This tutorial shows you how to set up, configure, and connect a self-hosted runner on a Mac mini to execute macOS pipelines.
Before you start
To complete the actions presented below, you must have:
- A Scaleway account logged into the console
- Owner status or IAM permissions allowing you to perform actions in the intended Organization
- A Mac mini
- A GitHub repository with administrator rights
- Installed a package manager. For the sake of this tutorial, we will use Homebrew, which is a popular package manager for macOS.
Preparing for installation
Before starting the installation process, create a dedicated user account named “gh-runner” on your Mac mini and add it to the admin group. Execute the following terminal commands:
# Create the 'gh-runner' user accountsudo dscl . -create /Users/gh-runnersudo dscl . -create /Users/gh-runner UserShell /bin/bashsudo dscl . -create /Users/gh-runner RealName "GitHub runner"sudo dscl . -create /Users/gh-runner UniqueID "1001"sudo dscl . -create /Users/gh-runner PrimaryGroupID 20sudo dscl . -create /Users/gh-runner NFSHomeDirectory /Users/gh-runner# Set the password of the user. Replace password with the actual password you want to configure for the user.sudo dscl . -passwd /Users/gh-runner password# Additional commands to create and configure the user...# Add 'gh-runner' to the 'admin' groupsudo dscl . -append /Groups/admin GroupMembership gh-runner
Use su
to enter the newly created gh-runner
account for configuring the self-hosted runner.
su gh-runner
Installing Git and Rosetta 2
Ensure Git and Rosetta 2 are installed on your Mac mini:
git --version# We assume you have the homebrew package manager installed. If not, follow the guides on https://brew.sh/ for details how to install it.brew install git# Install Rosetta 2 if not already installedsoftwareupdate --install-rosetta
Rosetta 2 is a translation technology developed by Apple for Macs with Apple Silicon processors, enabling them to run applications designed for Intel-based Macs by dynamically translating the software’s instructions to a format compatible with the new architecture.
Installing and configuring the Runner
-
Navigate to your GitHub repository and go to Settings.
-
Click Actions under Code and automation, then select Runners. A list of your configured runners displays.
-
Click New self-hosted runner to be redirected to the configuration page.
-
Choose macOS as the runner image and ARM64 as the architecture.
-
Follow the prompted shell commands to authenticate your machine, download the necessary runtime, and set up the runner. Do not start your runner yet.
NoteAfter selecting the runner image and architecture, GitHub prompts you to execute a sequence of shell commands. Those commands serve to authenticate your machine with your Github repository, download the necessary runtime, and set up the runner within your environment. Take note of these commands, as you will need to execute them on your Mac mini.
-
Create a
.env
file in the runner_work
folder for essential environment variables:# _work/.env fileImageOS=macos13XCODE_15_DEVELOPER_DIR=/Applications/Xcode.app/Contents/DeveloperAdd any additional environment variables required by your actions.
TipIf you have not yet installed Xcode on your machine, follow the official Apple Xcode documentation for further details.
-
Execute the
run.sh
script in your runner directory to complete the setup. -
Check that the runner is up and listening for jobs in the terminal and check the GitHub repository settings for the runner’s association and
Idle
status.
Using the runner in a workflow
The runner is authenticated to your repository and labeled with self-hosted
, macOS
, and ARM64
. Use it in your workflows by specifying these labels in the runs-on
field:
name: Sample workflowon:workflow_dispatch:jobs:build:runs-on: [self-hosted, macOS, ARM64]steps:- name: Install NodeJSrun: brew install node
Sudoers configuration (optional)
If actions require root privileges, configure the sudoers file using sudo visudo
. For private repositories, add:
gh-runner ALL=(ALL) NOPASSWD: ALL
Add application-level restrictions to avoid password prompts.
runner ALL= NOPASSWD: /bin/hostname# Or your additional applications with arguments:runner ALL= NOPASSWD: /bin/hostname,/your_dir/your_bin your_args
Conclusion
This tutorial guided you through setting up a self-hosted runner on an Apple silicon-based Mac mini for macOS pipelines. Your runner is now ready to be integrated into your workflows. For additional information, refer to the managing self-hosted runners documentation on GitHub.