wayofdev.homebrew

Panoramica Versioni Approfondimenti

<br>

<div align="center">
<img width="456" src="https://raw.githubusercontent.com/wayofdev/ansible-role-homebrew/master/assets/logo.gh-light-mode-only.png#gh-light-mode-only">
<img width="456" src="https://raw.githubusercontent.com/wayofdev/ansible-role-homebrew/master/assets/logo.gh-dark-mode-only.png#gh-dark-mode-only">
</div>

<br>

<br>

<div align="center">
<a href="https://actions-badge.atrox.dev/wayofdev/ansible-role-homebrew/goto"><img alt="Build Status" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fwayofdev%2Fansible-role-homebrew%2Fbadge&style=flat-square"/></a>
<a href="https://galaxy.ansible.com/wayofdev/homebrew"><img alt="Ansible Role" src="https://img.shields.io/ansible/role/59331?style=flat-square"/></a>
<a href="https://github.com/wayofdev/ansible-role-homebrew/tags"><img src="https://img.shields.io/github/v/tag/wayofdev/ansible-role-homebrew?sort=semver&style=flat-square" alt="Latest Version"></a>
<a href="https://galaxy.ansible.com/wayofdev/homebrew"><img alt="Ansible Quality Score" src="https://img.shields.io/ansible/quality/59331?style=flat-square"/></a>
<a href="https://galaxy.ansible.com/wayofdev/homebrew"><img alt="Ansible Role" src="https://img.shields.io/ansible/role/d/59331?style=flat-square"/></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/wayofdev/ansible-role-homebrew.svg?style=flat-square&color=blue" alt="Software License"/></a>
<a href="#"><img alt="Commits since latest release" src="https://img.shields.io/github/commits-since/wayofdev/ansible-role-homebrew/latest?style=flat-square"></a>
</div>
<br>

# Ansible Role: Homebrew

This role installs [Homebrew](https://brew.sh/) on macOS or Linux and sets up taps, packages, and casks. It includes retry loops to handle connection issues.

If you enjoy using this role, please consider giving it a **star**. Thank you!

<br>

## 🗂 Table of Contents

* [Requirements](#-requirements)
* [Role Variables](#-role-variables)
   * [Structure](#-structure)
   * [Tapping repositories](#-tapping-repositories)
   * [Packages: Installing, updating and removing](#-packages-installing-updating-and-removing)
   * [Casks: installing, updating and removing](#-casks-installing-updating-and-removing)
* [Example Playbook](#-example-playbook)
   * [for macOS machines](#-for-macos-machines)
   * [for Linux machines](#-for-linux-machines)
* [Development](#-development)
* [Testing](#-testing)
* [Dependencies](#-dependencies)
   * [for all](#-for-all)
   * [only macOS](#-only-macos)
   * [only Linux](#-only-linux)
* [Compatibility](#-compatibility)
* [License](#-license)
* [Author Information](#-author-information)
* [Credits and Resources](#-credits-and-resources)
* [Sponsors](#-sponsors)

<br>

## 📑 Requirements

* You need the latest version of Ansible. We stick to current versions and will use new features as they come (and update `meta/main.yml` for the minimum version).
* Ensure your OS is compatible. Check the [compatibility](#-compatibility) table for details.
* The `jmespath` library must be installed on the machine running the playbook (needed for the `json_query` filter).
* This role depends on other third-party roles on various operating systems. Check `requirements.yml` and the [dependencies](#-dependencies) section.

<br>

## 🔧 Role Variables

Below are the available variables, with example values (see `defaults/main.yml`). Additional variables are in `vars/main.yml`.

<br>

### → Structure

This variable points to the GitHub repository for Homebrew core. By default, the role checks for the latest release from the official Homebrew repository. If you want to use your own fork and disable latest release detection, set `homebrew_repository_use_master` to `true`.

```yaml
# Repository to install homebrew from
homebrew_repository: https://github.com/Homebrew/brew

# Set to true to use master branch instead of the latest release,
# or if using a custom fork specified in homebrew_repository
homebrew_repository_use_master: false

Setting this to true will update Homebrew and all installed packages:

# Upgrade all packages
homebrew_upgrade_all: true

Control the number of retry attempts and the delay between attempts if the homebrew install task fails:

# Number of retry attempts if a package / tap / cask installation fails
homebrew_retries: 32

# Delay between each retry attempt
homebrew_delay: 3

Set this to true to clear the Homebrew cache after installing or updating software.

homebrew_clear_cache: false

Specify the directory where applications installed via cask should go.

homebrew_cask_appdir: /Applications

If set to true, --greedy will be passed to check if an installed cask has a newer version.

homebrew_cask_greedy_mode: false

Disable Homebrew analytics which are collected by default.

homebrew_collect_analytics: false

→ Tapping repositories

Adding repositories (tapping):

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

Adding repositories, detailed with URLs and states:

homebrew_taps:
  # standard tap
  - name: homebrew/core

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

  # tap with a specific state
  - name: homebrew/cask-fonts
    state: present

Removing taps:

homebrew_taps:
  # set state: absent to remove taps
  - name: homebrew/cask-fonts
    state: absent

  - name: denji/nginx
    state: absent

→ Packages: Installing, updating and removing

To Add packages simply:

homebrew_packages:
  - wget
  - curl
  - nano

To Add packages with more options, such as state and path:

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

To Update packages:

homebrew_packages:
  # update Homebrew first and install wget in the default path
  - name: wget
    state: present
    update_homebrew: true

  # update Homebrew first and upgrade curl to the latest version in the default path
  - name: curl
    state: latest
    update_homebrew: true

To Remove packages:

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

→ Casks: installing, updating and removing

:warning: Notice: Casks only work on macOS. Refer to this post.

To Add casks simply:

homebrew_casks:
  - firefox
  - google-chrome
  - alfred
  - 1password

To Add casks with more options:

homebrew_casks:
  - name: firefox
    state: present

To Remove casks:

homebrew_casks:
  - name: firefox
    state: absent
  - name: google-chrome
    state: absent

📗 Example Playbook

→ for macOS machines

---
- hosts: all
  connection: local

  # 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 for macOS machines
    - wayofdev.homebrew

→ for Linux machines

---
- hosts: all
  connection: local

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

  vars:
    homebrew_user: linuxbrew  # can be skipped as auto-detected, but using the linuxbrew user is recommended
    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 for Linux machines, can be skipped if git is already installed
    - wayofdev.homebrew

⚙️ Development

To install dependencies and start development, check our Makefile.

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

$ make install

Install only python dependencies, assuming you already have poetry:

$ make install-deps

Install all git hooks:

$ make hooks

Lint all role files:

$ make lint

🧪 Testing

You can check Makefile for a full list of commands for testing locally and on remote machines. For local testing, these commands can test the role or individual tasks:

→ on localhost

:warning: Notice: By default, all tests run on your local machine!

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

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

# check for idempotency
$ make test-idempotent

# validate and install
$ export TASK_TAGS="brew-install,brew-update"
$ make test-tag

# run predefined task tags
$ 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

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

# or with make
$ make m-linux

→ over SSH

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

$ make m-remote

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