Tutorial

GitHub Actions is a powerful CI/CD platform that allows you to automate your software development workflows. While GitHub offers hosted runners, 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.

Prerequisites

Before you begin, ensure you have:

• A Mac Mini (register on Roundfleet)
• A GitHub repository with administrator rights
• A package manager installed (preferably Homebrew)
• Git installed on your system

Step 1: Create a Dedicated User Account

First, create a dedicated user account for the GitHub Actions runner:

# 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 for the user
sudo dscl . -passwd /Users/gh-runner your_password

# Add 'gh-runner' to the 'admin' group
sudo dscl . -append /Groups/admin GroupMembership gh-runner

Switch to the new user account:

su gh-runner

Step 2: Install Required Software

Install Git and Rosetta 2 (if using Apple Silicon):

# Install Git if not already installed
brew install git

# Install Rosetta 2 for Apple Silicon Macs
softwareupdate --install-rosetta

Step 3: Configure the GitHub Actions Runner

1. Go to your GitHub repository
2. Navigate to Settings > Actions > Runners

3. Click "New self-hosted runner" (https://github.com/<username>/<repository>/settings/actions/runners/new)
4. Select macOS as the runner image and ARM64 as the architecture
5. Follow the provided commands to download and configure the runner

Create a .env file in the runner's _work directory:

# _work/.env file
ImageOS=macos15
XCODE_15_DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer

6. Execute the run.sh script in your runner directory to complete the setup.
7. 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.

Step 4: Configure Sudoers (Optional)

If your actions require root privileges, configure the sudoers file:

sudo visudo

Add the following line:

gh-runner ALL=(ALL) NOPASSWD: ALL

Step 5: Using the Runner in Workflows

Configure your GitHub Actions workflow to use the self-hosted runner:

name: Sample workflow

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64]
    steps:
      - name: Install NodeJS
        run: brew install node

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:

runs-on: [self-hosted, macOS, ARM64]

Best Practices

• Keep your runner software up to date
• Regularly monitor runner logs for issues
• Use specific labels for different types of runners
• Implement proper security measures
• Consider using multiple runners for load balancing

Troubleshooting

Common issues and solutions:

1. Runner not connecting:

   • Check network connectivity
   • Verify GitHub token validity
   • Ensure proper permissions

2. Build failures:

   • Check Xcode installation
   • Verify required dependencies
   • Review workflow logs

3. Permission issues:

   • Verify user permissions
   • Check sudoers configuration
   • Review file system permissions

Conclusion

You now have a self-hosted GitHub Actions runner configured on your Mac Mini. This setup provides you with more control over your CI/CD environment and allows you to run macOS-specific workflows efficiently.

Remember to regularly maintain your runner and keep it updated with the latest security patches and software versions.