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 Macfleet)
• 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.

Macfleet Installation Guide

Macfleet is a powerful fleet management solution designed specifically for cloud-hosted Mac Mini environments. As a Mac Mini cloud hosting provider, you can use Macfleet to monitor, manage, and optimize your entire fleet of virtualized Mac instances.

This installation guide will walk you through setting up Macfleet monitoring across macOS, Windows, and Linux systems to ensure comprehensive oversight of your cloud infrastructure.

🍎 macOS

• Download the .dmg file for Mac here
• Double-click the downloaded .dmg file
• Drag the Macfleet app to the Applications folder
• Eject the .dmg file
• Open System Preferences > Security & Privacy
  • Privacy tab > Accessibility
  • Check Macfleet to allow monitoring
• Launch Macfleet from Applications
• Tracking starts automatically

🪟 Windows

• Download the .exe file for Windows here
• Right-click the .exe file > "Run as administrator"
• Follow the installation wizard
• Accept terms and conditions
• Allow in Windows Defender if prompted
• Grant application monitoring permissions
• Launch Macfleet from Start Menu
• The application begins tracking automatically

🐧 Linux

• Download the .deb package (Ubuntu/Debian) or .rpm (CentOS/RHEL) here
• Install using your package manager
  • Ubuntu/Debian: sudo dpkg -i Macfleet-linux.deb
  • CentOS/RHEL: sudo rpm -ivh Macfleet-linux.rpm
• Allow X11 access permissions if prompted
• Add user to appropriate groups if necessary
• Launch Macfleet from Applications menu
• The application begins tracking automatically

Note: After installation on all systems, log in with your Macfleet credentials to sync data with your dashboard.