---
title: Configuring a GitHub Actions Runner on a Mac mini for enhanced CI/CD
description: Learn the detailed steps to set up and configure a self-hosted GitHub Actions runner on a bare metal Mac mini, optimizing your Continuous Integration and Continuous Deployment workflows for macOS.
tags: mac m1 github-actions ci/cd apple-silicon self-hosted-runner
products:
- apple-silicon
dates:
validation: 2025-05-19
posted: 2024-01-31
validation_frequency: 12
difficulty: beginner
usecase:
- deploy-external-software
ecosystem:
- third-party
---
import image from './assets/scaleway-gh-runner-mac-arm64.webp'
import image2 from './assets/scaleway-gh-runner-status-idle.webp'
import Requirements from '@macros/iam/requirements.mdx'
GitHub Actions is a powerful 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 provide increased control and customization for your CI/CD setup. This tutorial guides you through setting up, configuring, and connecting a self-hosted runner on a Mac mini to execute macOS pipelines.
- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- A [Mac mini](/apple-silicon/how-to/create-mac-mini/)
- A GitHub repository with administrator rights
- Installed a package manager, preferably [Homebrew](https://brew.sh/index)
GitHub [recommends](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security) using self-hosted runners with private repositories for enhanced security.
## 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:
```bash
# Create the 'gh-runner' user account
sudo dscl . -create /Users/gh-runner
sudo dscl . -create /Users/gh-runner UserShell /bin/bash
sudo dscl . -create /Users/gh-runner RealName "GitHub runner"
sudo dscl . -create /Users/gh-runner UniqueID "1001"
sudo dscl . -create /Users/gh-runner PrimaryGroupID 20
sudo 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
# Add 'gh-runner' to the 'admin' group
sudo dscl . -append /Groups/admin GroupMembership gh-runner
```
Use `su` to switch to the newly created `gh-runner` account for configuring the self-hosted runner.
```bash
su gh-runner
```
## Installing Git and Rosetta 2
Ensure Git and Rosetta 2 are installed on your Mac mini:
```bash
git --version
# Assuming you have Homebrew installed. If not, follow the guides on https://brew.sh/ to install it.
brew install git
# Install Rosetta 2 if not already installed
softwareupdate --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
1. Navigate to your [GitHub repository](https://github.com/) and go to **Settings**.
2. Click **Actions** under **Code and automation**, then select **Runners**. A list of your configured runners displays.
3. Click **New self-hosted runner** to be redirected to the configuration page.
4. Choose **macOS** as the runner image and **ARM64** as the architecture.
5. Follow the prompted shell commands to authenticate your machine, download the necessary runtime, and set up the runner. Do not start your runner yet.
After selecting the runner image and architecture, GitHub prompts you to execute a sequence of shell commands. These commands serve to authenticate your machine with your GitHub repository, download the necessary runtime, and set up the runner within your environment. Execute these commands on your Mac mini.
6. Create a `.env` file in the runner `_work` folder for essential environment variables:
```bash
# _work/.env file
ImageOS=macos13
XCODE_15_DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
```
Add any additional environment variables required by your actions.
If you have not yet installed Xcode on your machine, follow the [official Apple Xcode documentation](https://developer.apple.com/documentation/safari-developer-tools/installing-xcode-and-simulators) for further details.
7. Execute the `run.sh` script in your runner directory to complete the setup.
8. Verify 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:
```yaml
name: Sample workflow
on:
workflow_dispatch:
jobs:
build:
runs-on: [self-hosted, macOS, ARM64]
steps:
- name: Install NodeJS
run: brew install node
```
## Sudoers configuration (optional)
If actions require root privileges, configure the sudoers file using `sudo visudo`. For private repositories, add:
```bash
gh-runner ALL=(ALL) NOPASSWD: ALL
```
Add application-level restrictions to avoid password prompts.
```bash
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](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners).