install github actions runner mac
Jump toUpdate content

Installing a Github Actions runner on a Mac mini

Reviewed on 11 August 2023Published on 11 August 2023
  • mac
  • m1
  • github-actions
Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

  • you are the Owner of the Scaleway Organization in which the actions will be carried out, or
  • you are an IAM user of the Organization, with a policy granting you the necessary permission sets

You have:

  • You have an account and are logged into the Scaleway console
  • You have created a Mac mini
  • You have a Github repository with administrator rights.
  • You have installed a package manager. For the sake of this tutorial, we will use Homebrew which is a popular package manager for macOS.


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.

Installing the runner

  1. Navigate to the main page of your GitHub repository and click Settings.

  2. Click Actions, located under Code and automation on the left sidebar. A menu displays.

  3. Click Runners.

  4. Click the New self-hosted runner button. You are redirected to the self-hosted runners configuration page.

  5. Select macOS as a runner image and ARM64 as an architecture.


    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.

  6. Connect to your Mac mini using VNC.


    In this instance, SSH cannot be used as the runner service needs a graphical session to be started.

  7. Open a terminal and execute the commands previously prompted by Github. Don’t launch the runner yet.


    This tutorial assumes that you picked the default settings when prompted during step 6.

Configuring the runner

Once the runner is installed, you must configure it to use the dependencies needed for your workflows.

  1. 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.

  2. Create a file named .path in the root of the runner directory and define the content of the runner’s $PATH variable 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:

  3. Specify your environment variables in the .env file, 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 .env:


    The .env file follows the bash syntax to set variables.

  4. You can create your own scripts to execute before or after a job.

Configuring the service

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.

  1. 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.

  2. Install and run the service:

./svc.sh install
./svc.sh start

Using the runner in a workflow

The runner is already authenticated to your repository and referenced with the labels self-hosted, macOS and ARM64. 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 workflow
runs-on: [self-hosted, macOS, ARM64]
- name: Install NodeJS
run: 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.