Ansible Role: Homebrew

Installs Homebrew on macOS or Linux, and configures taps, packages and casks. Package uses retry loops to deal with connectivity issues.

If you like/use this role, please consider starring it. Thanks!

🗂 Table of Contents

• Requirements
• Role Variables
  • Structure
  • Tapping repositories
  • Packages: Installing, updating and removing
  • Casks: installing, updating and removing
• Example Playbook
  • for macOS machines
  • for Linux machines
• Development
• Testing
• Dependencies
  • for all
  • only macOS
  • only Linux
• Compatibility
• License
• Author Information
• Credits and Resources
• Sponsors

📑 Requirements

• Up-to-date version of ansible. During maintenance/development, we stick to ansible versions and will use new features if they are available (and update meta/main.yml for the minimum version).
• Compatible OS. See compatibility table.
• jmespath library needs to be installed on the host running the playbook (needed for the json_query filter).
• Role has dependencies on third-party roles on different operating systems. See requirements.yml and dependencies section.

🔧 Role Variables

Available variables are listed below, along with example values (see defaults/main.yml). Additional variables are stored in vars/main.yml.

→ Structure

GitHub repository variable for Homebrew core. By default, role checks for latest release from official Homebrew repository, if you are changing homebrew_repository to your fork and want to use master branch and turn off latest release autodetect, then set homebrew_repository_use_master variable to true

# From which repository should we install homebrew?
homebrew_repository: https://github.com/Homebrew/brew

# Set to true if you want to use master branch instead of release auto-detect,
# or you use custom fork specified in homebrew_repository
homebrew_repository_use_master: false

When set to true, will update Homebrew itself and upgrade all homebrew packages:

# Run task to upgrade all packages
homebrew_upgrade_all: true

Variable controls retry times and delay to wait between retries, if homebrew install task failed:

# How much times to retry, if installation of package / tap / cask fails ?
# This can happen during network problems.
homebrew_retries: 32

# Delay between each retry attempt.
homebrew_delay: 3

Set to true to remove the Homebrew cache after any new software is installed or updated.

homebrew_clear_cache: false

Directory where applications installed via cask should be installed.

homebrew_cask_appdir: /Applications

If set to true, passes --greedy to brew cask outdated when checking if an installed cask has a newer version available.

homebrew_cask_greedy_mode: false

Turn off homebrew analytics, which are collected by default.

homebrew_collect_analytics: false

→ Tapping repositories

Adding (tapping) repositories

homebrew_taps:
  - homebrew/core
  - homebrew/cask-versions
  - homebrew/cask-fonts

Adding (tapping) repositories, in more verbose way, defining urls and states:

homebrew_taps:
  # just tap
  - name: homebrew/core

  # tap from custom repository
  - name: denji/nginx
    url: https://github.com/denji/homebrew-nginx

  # tap with defined custom state
  - name: homebrew/cask-fonts
    state: present

Removing taps:

homebrew_taps:
  # define state: absent to delete taps
  - name: homebrew/cask-fonts
    state: absent

  - name: denji/nginx
    state: absent

→ Packages: Installing, updating and removing

Adding packages in simple way:

homebrew_packages:
  - wget
  - curl
  - nano

Adding packages in advanced way, defining state, path, and other options:

homebrew_packages:
  # install to custom path
  - name: wget
    state: present
    path: /opt/custom/path/bin

Updating packages:

homebrew_packages:
  # update homebrew first and install formula wget with 'brew' in default path
  - name: wget
    state: present
    update_homebrew: true

  # update homebrew first and upgrade formula curl to the latest available with 'brew' in default path
  - name: curl
    state: latest
    update_homebrew: true

Removing packages:

homebrew_packages:
  - name: wget
    state: absent
  - name: curl
    state: absent

→ Casks: installing, updating and removing

⚠️ Notice: Casks are supported only on macOS. See this post.

Adding casks in simple way:

homebrew_casks:
  # Installing list of casks
  - firefox
  - google-chrome
  - alfred
  - 1password

Adding casks with advanced options:

homebrew_casks:
  # Installing firefox cask
  - name: firefox
    state: present

Removing casks:

homebrew_casks:
  # define state: absent to delete
  - name: firefox
    state: absent
  - name: google-chrome
    state: absent

📗 Example Playbook

→ for macOS machines

---
- hosts: all
  connection: local

  # is needed when running over SSH
  environment:
    - PATH: "{{ homebrew_search_paths | join(':') }}:{{ ansible_env.PATH }}"

  vars:
    homebrew_taps:
      - homebrew/core
      - homebrew/cask
      - homebrew/cask-fonts
      - yt-dlp/taps
    homebrew_packages:
      - ssh-copy-id  # from homebrew/core
      - yt-dlp  # from yt-dlp/taps
    homebrew_casks:
      - firefox
      - google-chrome
      - font-fira-code-nerd-font  # from homebrew/cask-fonts
    homebrew_retries: 12
    homebrew_delay: 3
    homebrew_clear_cache: false
    homebrew_collect_analytics: false

  roles:
    - elliotweiser.osx-command-line-tools  # only on macOS machines
    - wayofdev.homebrew

→ for Linux machines

---
- hosts: all
  connection: local

  # is needed when running over SSH
  environment:
    - PATH: "{{ homebrew_search_paths | join(':') }}:{{ ansible_env.PATH }}"

  vars:
    homebrew_user: linuxbrew  # FYI: can be skipped, as automatically detected, but linuxbrew user is recommended way for installing Homebrew with Linux
    homebrew_group: linuxbrew  # same as homebrew_user

    homebrew_taps:
      - homebrew/core
      - yt-dlp/taps
    homebrew_packages:
      - ssh-copy-id  # from homebrew/core
      - yt-dlp  # from yt-dlp/taps
    homebrew_retries: 12
    homebrew_delay: 3
    homebrew_clear_cache: false
    homebrew_collect_analytics: false

  roles:
    - geerlingguy.git  # only on linux machines, and can be skipped if machine has git
    - wayofdev.homebrew

⚙️ Development

To install dependencies and start development you can check contents of our Makefile

Install poetry using poetry-bin and all dev python dependencies:

$ make install

Install only python dependencies, assuming that you already have poetry:

$ make install-deps

Install all git hooks:

$ make hooks

Lint all role files:

$ make lint

🧪 Testing

You can check Makefile to get full list of commands for remote and local testing. For local testing you can use these comands to test whole role or separate tasks:

→ on localhost

⚠️ Notice: By defaut all tests are running against your local machine!

# run all tags with scenario from ./tests/test.yml
$ make test

# or test-tag without any parameters
$ make test-tag

# run idempotency check
$ make test-idempotent

# run tasks that validate config file and does installation
$ export TASK_TAGS="brew-install,brew-update"
$ make test-tag

# run by predefined command that executes only one tag
$ make test-install
$ make test-analytics
$ make test-update
$ make test-taps
$ make test-packages
$ make test-casks

# run molecule tests on localhost
$ poetry run molecule test --scenario-name default-macos-on-localhost -- -vvv

# or with make command
$ make m-local

# runs molecule with docker driver
$ poetry run molecule test --scenario-name default -- -vvv

# or with make file
$ make m-linux

→ over SSH

# run molecule scenarios against remote machines over SSH
# this will need VM setup and configuration
$ poetry run molecule test --scenario-name default-macos-over-ssh -- -vvv

$ make m-remote

# tags also can be passed
$ export TASK_TAGS="brew-install,brew-update"
$ make m-remote

📦 Dependencies

Installation handled by Makefile and requirements are defined in requirements.yml

→ for all

• ansible.community.general

→ only macOS

• elliotweiser.osx-command-line-tools

→ only Linux

• geerlingguy.git

🧩 Compatibility

This role has been tested on these systems:

system / container	tag
macos	monterey
macos	big-sur
ubuntu	jammy
ubuntu	focal
debian	bullseye
debian	buster
fedora	36
fedora	35
centos	8
centos	7

🤝 License

🙆🏼‍♂️ Author Information

This role was created in 2022 by lotyp / wayofdev.

🧱 Credits and Resources

Inspired by:

• role-homebrew-retry by @niall-byrne
• homebrew role created by @geerlingguy as a part of ansible-collection-mac
• official Homebrew installer script

🫡 Contributors

🤑 Sponsors

Role development and testing was done on Parallels Desktop Pro Edition and License was provided by Parallels