Installing a Github Actions runner on a Mac mini
You may need certain IAM permissions to carry out some actions described on this page. This means:
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.
Github recommends to only use self-hosted runners with private repositories for security reasons.
Navigate to the main page of your GitHub repository and click Settings.
Click Actions, located under Code and automation on the left sidebar. A menu displays.
Click the New self-hosted runner button. You are redirected to the self-hosted runners configuration page.
Select macOS as a runner image and ARM64 as an architecture.Note:
After 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.
Connect to your Mac mini using VNC.Note:
In this instance, SSH cannot be used as the runner service needs a graphical session to be started.
Open a terminal and execute the commands previously prompted by Github. Don’t launch the runner yet.Note:
This tutorial assumes that you picked the default settings when prompted during step 6.
Once the runner is installed, you must configure it to use the dependencies needed for your workflows.
Install the dependencies needed for your workflows. For example, Homebrew is a popular package manager for macOS that can be installed with the following command:/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Unlike online runners where dependencies have to be installed each time a workflow is run, self-hosted runners allow you to prepare all the dependencies that you need.
Create a file named
.pathin the root of the runner directory and define the content of the runner’s
$PATHvariable within it. As the runner uses an empty user profile, its path must be configured accordingly. This file is located in the root of the runner directory. To be able to use during a workflow the homebrew command previously installed, append this content at the end of the .path file::/opt/homebrew/bin
Specify your environment variables in the
.envfile, following the same rationale as the path configuration. This file is also located in the root of the runner directory. To tell homebrew to avoid doing cleanups during workflow in order to not waste compute time, add the following variable to
.envfile follows the bash syntax to set variables.
You can create your own scripts to execute before or after a job.
After configuring the runner, you can configure it as a service in order to run it in the background and follow the lifecycle of your Mac mini from boot time to shut down, as well as restarts in case of failures.
Your Mac must be configured to log-in automatically. Go to System Preferences > Users and Groups > Login Options and select the m1 user in the Automatic Login picklist.
Install and run the service:
./svc.sh install./svc.sh start
The runner is already authenticated to your repository and referenced with the labels
You can use it in your workflows, by populating
jobs.<job_id>.runs-on with those labels.
For example, the following workflow will use the self-hosted runner to install Node.js using Homebrew:
name: Sample workflowon:workflow_dispatch:jobs:build:runs-on: [self-hosted, macOS, ARM64]steps:- name: Install NodeJSrun: brew install node
This tutorial showed you how to set up, configure, and connect a self-hosted runner on a Mac mini for executing macOS pipelines. The runner is now ready to be used in your workflows. For more information, visit Managing self-hosted runners on Github Docs.