MacAutomation

A comprehensive Ansible-based automation framework for managing macOS build machines and development environments

Author

Assaf Feuerstein
DevOps Engineer | Infrastructure Automation Specialist

---

Overview

MacAutomation is a production-ready Ansible framework designed to automate the provisioning, configuration, and maintenance of macOS machines. It's particularly useful for:

• CI/CD Build Farms: Automate configuration of Mac build agents for Unity, Xcode, and mobile development
• Developer Workstations: Standardize development environments across teams
• Apple Silicon & Intel Support: Full support for both ARM64 (M1/M2/M3/M4) and x86_64 architectures

Features

Development Tools

• Xcode - Automated installation, configuration, and iOS SDK setup
• Unity Hub & Unity Editor - Multi-version Unity management with module support
• Android SDK - Command-line tools and platform tools installation
• Flutter - Cross-platform SDK installation and configuration

Runtime Environments

• .NET SDK/Runtime - Microsoft .NET installation with workload support
• Ruby (rbenv) - Ruby version management with gem installation
• Node.js - NVM-based Node.js management
• Java - OpenJDK and Corretto support

System Tools

• Homebrew - Package and cask management
• Rosetta 2 - Intel compatibility layer for Apple Silicon
• CocoaPods - iOS dependency management
• Google Cloud SDK - gcloud CLI tools

Monitoring

• Prometheus Node Exporter - System metrics collection for monitoring

Project Structure

MacAutomation/
├── ansible.cfg              # Ansible configuration
├── hosts.ini.example        # Example inventory file
├── requirements.yml         # Ansible Galaxy dependencies
│
├── # Quick-Start Example Playbooks (root directory)
├── xcode.yml               # Install Xcode
├── unity.yml               # Install Unity Hub + Editor
├── flutter.yml             # Install Flutter SDK
├── dev-setup.yml           # Full developer workstation setup
├── monitoring.yml          # Prometheus Node Exporter
├── brew-upgrade.yml        # Update Homebrew packages
├── mac-cleanup.yml         # Cleanup disk space
│
├── group_vars/
│   └── all.yml             # Global variables
├── host_vars/
│   └── example-mac-01.yml  # Per-host variables example
├── roles/
│   ├── homebrew/           # Homebrew package management
│   ├── xcode/              # Xcode installation & configuration
│   ├── xcode-cli-tools/    # Xcode Command Line Tools
│   ├── unity-install/      # Unity Editor installation
│   ├── unityhub-install/   # Unity Hub installation
│   ├── flutter/            # Flutter SDK
│   ├── android-sdk/        # Android development tools
│   ├── dotnet-sdk/         # .NET SDK installation
│   ├── cocoapods-install/  # CocoaPods gem
│   ├── rbenv-install/      # Ruby version management
│   ├── rosetta-install/    # Rosetta 2 for Apple Silicon
│   ├── prometheus-node-exporter/  # Monitoring agent
│   └── gcloud/             # Google Cloud SDK
├── playbooks/              # Advanced/composite playbooks
│   ├── site.yml            # Full machine setup
│   ├── dev-tools.yml       # Development tools bundle
│   └── cleanup.yml         # Maintenance cleanup
└── scripts/
    ├── bootstrap.sh        # Initial machine setup
    └── test-connection.sh  # Test Ansible connectivity

Quick Start

Prerequisites

1. Control Machine (where you run Ansible):

   • Python 3.9+
   • Ansible 2.15+
   • SSH access to target machines

2. Target Machines (macOS hosts):

   • macOS 12 (Monterey) or later
   • SSH enabled
   • Admin user with sudo privileges

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/MacAutomation.git
   cd MacAutomation

2. Install Ansible dependencies:

   pip install ansible
   ansible-galaxy collection install community.general

3. Configure your inventory:

   cp hosts.ini.example hosts.ini
   # Edit hosts.ini with your target machines

4. Configure variables:

   # Edit group_vars/all.yml with your settings
   # Create host_vars/<hostname>.yml for per-host configuration

Running Playbooks

Quick Examples (from root directory):

# Install Xcode
ansible-playbook xcode.yml -i hosts.ini -e "xcode_version=15.4"

# Install Unity
ansible-playbook unity.yml -i hosts.ini -e "unity_version=2022.3.20f1"

# Install Flutter
ansible-playbook flutter.yml -i hosts.ini

# Full developer setup
ansible-playbook dev-setup.yml -i hosts.ini

# Setup monitoring
ansible-playbook monitoring.yml -i hosts.ini

# Update Homebrew packages
ansible-playbook brew-upgrade.yml -i hosts.ini

# Cleanup disk space
ansible-playbook mac-cleanup.yml -i hosts.ini

Advanced Playbooks (from playbooks/ directory):

# Full machine provisioning
ansible-playbook playbooks/site.yml -i hosts.ini

# Development tools bundle
ansible-playbook playbooks/dev-tools.yml -i hosts.ini

Configuration

Global Variables (group_vars/all.yml)

---
# Build user configuration
build_user: "buildagent"

# Xcode settings
xcode_version: "15.4"

# Unity settings  
unity_version: "2022.3.20f1"
unity_modules: "android,ios,webgl"

# Flutter settings
flutter_version: "3.19.0"

# .NET settings
dotnet_version: "8.0.100"

Host Variables (host_vars/<hostname>.yml)

---
# Override settings per host
build_user: "developer"
xcode_version: "16.0"

Roles Reference

Role	Description	Key Variables
homebrew	Install Homebrew packages/casks	brew_package, brew_cask
xcode	Install and configure Xcode	xcode_version
unity-install	Install Unity Editor versions	unity_version, unity_modules
unityhub-install	Install Unity Hub	-
flutter	Install Flutter SDK	flutter_version
android-sdk	Install Android SDK tools	-
dotnet-sdk	Install .NET SDK	dotnet_version
cocoapods-install	Install CocoaPods	cocoapods_version
rosetta-install	Install Rosetta 2 (ARM64 only)	-
gcloud	Install Google Cloud SDK	-
prometheus-node-exporter	Install Prometheus exporter	node_exporter_version

Advanced Usage

Custom Playbooks

Create custom playbooks by combining roles:

---
- name: Configure Mobile Build Agent
  hosts: mobile_builders
  become: yes
  roles:
    - rosetta-install
    - homebrew
    - xcode
    - android-sdk
    - flutter
    - cocoapods-install

Tags

Use tags for selective execution:

# Install only Homebrew packages
ansible-playbook playbooks/site.yml --tags "homebrew"

# Skip monitoring setup
ansible-playbook playbooks/site.yml --skip-tags "monitoring"

Dry Run

Preview changes without applying:

ansible-playbook playbooks/site.yml --check --diff

Security Considerations

• SSH Key Authentication: Always use SSH keys instead of passwords
• Ansible Vault: Use vault for sensitive data (API keys, certificates)
• Least Privilege: Create dedicated build users with minimal required permissions
• No Credentials in Code: This repository contains no credentials or secrets

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• The Ansible community for the excellent automation framework
• Apple for macOS and Xcode
• Unity Technologies for Unity Hub CLI documentation
• All contributors and users of this project

---

Built with ❤️ by Assaf Feuerstein