ci: pin brew-installed utilities to specific versions for supply-chain hardening

Author: mikehardy

.github/homebrew-rnfb/Formula/applesimutils.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+# RNFB CI vendored formula — do not install from third-party taps in workflows.
+# Upstream: wix/homebrew-brew @ 8f636f84541e — AppleSimulatorUtils 0.9.12
+# Update: see okf-bundle/ci-workflows/ios.md#pinned-homebrew-utilities
+
+class Applesimutils < Formula
+  desc "Apple simulator utilities"
+  homepage "https://github.com/wix/AppleSimulatorUtils"
+  url "https://github.com/wix/AppleSimulatorUtils/releases/download/0.9.12/AppleSimulatorUtils-0.9.12.tar.gz"
+  sha256 "4d6d02311959388ff5c28e2f4781848dbe1ca07f34b1d81d273940e099020b09"
+
+  bottle do
+    root_url "https://github.com/wix/AppleSimulatorUtils/releases/download/0.9.12"
+
+    sha256 arm64_big_sur: "3373d85ea6051e77865b0a22960eb0b5d63f3126c7c99232d0b6b9c83ee2c133"
+    sha256 catalina:      "530e29950dba6d11ca6da6841d24b84d835f8215836664d6e6ce8b23acce4a51"
+    sha256 mojave:        "3373d85ea6051e77865b0a22960eb0b5d63f3126c7c99232d0b6b9c83ee2c133"
+    sha256 high_sierra:   "3373d85ea6051e77865b0a22960eb0b5d63f3126c7c99232d0b6b9c83ee2c133"
+    sha256 sierra:        "3373d85ea6051e77865b0a22960eb0b5d63f3126c7c99232d0b6b9c83ee2c133"
+    sha256 big_sur:       "3373d85ea6051e77865b0a22960eb0b5d63f3126c7c99232d0b6b9c83ee2c133"
+  end
+
+  depends_on xcode: ["8.0", :build]
+
+  def install
+    system "./buildForBrew.sh", prefix
+  end
+
+  test do
+    system "#{bin}/applesimutils", "--help"
+  end
+end

.github/homebrew-rnfb/Formula/xcbeautify.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# RNFB CI vendored formula — do not install from live homebrew-core in workflows.
+# Upstream: Homebrew/homebrew-core @ f2e343d17882 — xcbeautify 3.2.1
+# Update: see okf-bundle/ci-workflows/ios.md#pinned-homebrew-utilities
+
+class Xcbeautify < Formula
+  desc "Little beautifier tool for xcodebuild"
+  homepage "https://github.com/cpisciotta/xcbeautify"
+  url "https://github.com/cpisciotta/xcbeautify/archive/refs/tags/3.2.1.tar.gz"
+  sha256 "7575dcb90e4650f8d8f66b92ca2f3eaa5ad9feddda7bf3c63aeb0edca199aa80"
+  license "MIT"
+
+  bottle do
+    sha256 cellar: :any_skip_relocation, arm64_tahoe:   "55d10b6b29942408802a3f7c141c8245b310054331c39be16f027f93867ad005"
+    sha256 cellar: :any_skip_relocation, arm64_sequoia: "f1094ef28d3e6f734cc58b43201a7112218b2518ed5b47b0c4e3242071a90742"
+    sha256 cellar: :any,                 arm64_sonoma:  "f65b81e0e1d354fc026fda8e4006579b99e764a5bee9cdb20343a432c902f84a"
+    sha256 cellar: :any,                 sonoma:        "da329e9b36ffc742e9dcba04f9bc2d2dcb05e41ecb9d902b5ab016145a46ac2c"
+    sha256 cellar: :any_skip_relocation, arm64_linux:   "0699fc7ed411b8e6875d2273dd230b83947a10f38471e59ff953a57283cb4c26"
+    sha256 cellar: :any_skip_relocation, x86_64_linux:  "1121ea99822c46089101d09aa4d43ad5679c5883f6c2212e712ba016db5a3ffe"
+  end
+
+  # needs Swift tools version 6.1.0
+  uses_from_macos "swift" => :build, since: :sequoia
+  uses_from_macos "libxml2"
+
+  on_sequoia do
+    # Workaround for https://github.com/apple/swift-argument-parser/issues/827
+    # Conditional should really be Swift >= 6.2 but not available so using
+    # a check on the specific ld version included with Xcode >= 26
+    depends_on xcode: :build if DevelopmentTools.ld64_version >= "1221.4"
+  end
+
+  def install
+    args = if OS.mac?
+      %w[--disable-sandbox]
+    else
+      %w[--static-swift-stdlib -Xswiftc -use-ld=ld]
+    end
+    system "swift", "build", *args, "--configuration", "release"
+    bin.install ".build/release/xcbeautify"
+    generate_completions_from_executable(bin/"xcbeautify", "--generate-completion-script")
+  end
+
+  test do
+    log = "CompileStoryboard /Users/admin/MyApp/MyApp/Main.storyboard (in target: MyApp)"
+    assert_match "[MyApp] Compiling Main.storyboard",
+      pipe_output("#{bin}/xcbeautify --disable-colored-output", log).chomp
+    assert_match version.to_s,
+      shell_output("#{bin}/xcbeautify --version").chomp
+  end
+end

.github/workflows/scripts/install-homebrew-rnfb.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Install vendored RNFB Homebrew formulae (Brew 6+ requires a tap, not bare --formula paths).
+# Pin/update docs: okf-bundle/ci-workflows/ios.md#pinned-homebrew-utilities
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $0 <formula> [<formula> ...]" >&2
+  exit 1
+fi
+
+TAP_ROOT="$(brew --repository)/Library/Taps/invertase/homebrew-rnfb"
+mkdir -p "$TAP_ROOT"
+cp -R .github/homebrew-rnfb/Formula "$TAP_ROOT/"
+
+export HOMEBREW_NO_AUTO_UPDATE=1
+brew trust invertase/rnfb
+
+# GHA images often ship homebrew-core formulae with the same names. Brew refuses to
+# install invertase/rnfb/<name> while core <name> is still in the Cellar.
+for formula in "$@"; do
+  if brew list --formula "$formula" &>/dev/null; then
+    echo "Uninstalling existing ${formula} before invertase/rnfb install..."
+    brew uninstall --formula "$formula"
+  fi
+done
+
+install_args=()
+for formula in "$@"; do
+  install_args+=("invertase/rnfb/${formula}")
+done
+brew install "${install_args[@]}"

.github/workflows/tests_e2e_ios.yml

@@ -264,14 +264,15 @@ jobs:
           launchctl unload -w /System/Library/LaunchAgents/com.apple.ReportCrash.plist
           sudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.ReportCrash.Root.plist
 
+      # Vendored Homebrew formulae — pin/update: okf-bundle/ci-workflows/ios.md#pinned-homebrew-utilities
       - name: Install brew utilities
         # https://github.com/nick-fields/retry/releases
         uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
         with:
           timeout_minutes: 5
           retry_wait_seconds: 60
           max_attempts: 3
-          command: HOMEBREW_NO_AUTO_UPDATE=1 brew tap wix/brew && HOMEBREW_NO_AUTO_UPDATE=1 brew install applesimutils xcbeautify
+          command: bash .github/workflows/scripts/install-homebrew-rnfb.sh applesimutils xcbeautify
 
       - name: Build iOS App Debug
         if: contains(matrix.buildmode, 'debug')

.github/workflows/tests_e2e_other.yml

@@ -219,14 +219,15 @@ jobs:
       - name: Start Firestore Emulator
         run: yarn tests:emulator:start-ci
 
+      # Vendored Homebrew formulae — pin/update: okf-bundle/ci-workflows/ios.md#pinned-homebrew-utilities
       - name: Install brew utilities
         # https://github.com/nick-fields/retry/releases
         uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
         with:
           timeout_minutes: 5
           retry_wait_seconds: 60
           max_attempts: 3
-          command: HOMEBREW_NO_AUTO_UPDATE=1 brew tap wix/brew && HOMEBREW_NO_AUTO_UPDATE=1 brew install xcbeautify
+          command: bash .github/workflows/scripts/install-homebrew-rnfb.sh xcbeautify
 
       - name: Build macos App
         run: |

CONTRIBUTING.md

@@ -99,8 +99,7 @@ cd react-native-firebase
 
 ```bash
 yarn
-brew tap wix/brew
-brew install applesimutils xcbeautify
+bash .github/workflows/scripts/install-homebrew-rnfb.sh applesimutils xcbeautify
 ```
 
 > Note that this project is a mono-repo, so you only need to install NPM dependencies once at the root of the project with `yarn`.

okf-bundle/ci-workflows/ios.md

@@ -221,3 +221,93 @@ rg 'Coverage summary|jet-coverage' detox-step.log
 - **Release vs debug** — matrix runs both; each has separate artifacts (`debug` / `release` in the artifact name).
 - **Retry** — Pre-Boot retries up to 3 times with 60s between attempts (clean shutdown + boot each time).
 - **Do not boot the simulator only inside Detox** — historical races where the testee never sent “ready” to the Detox proxy; pre-boot remains mandatory.
+
+### Pinned Homebrew utilities
+
+CI installs macOS build helpers from **vendored formulae** in `.github/homebrew-rnfb/Formula/` instead of live taps (`wix/brew`, `homebrew-core`). Each formula file is frozen in git with pinned `url`, source `sha256`, and bottle hashes — similar in spirit to SHA-pinned GitHub Actions.
+
+| Formula | Version | Upstream source | Used in |
+|---------|---------|-----------------|---------|
+| `applesimutils.rb` | 0.9.12 | [wix/homebrew-brew](https://github.com/wix/homebrew-brew) @ `8f636f84541e` | iOS e2e (`tests_e2e_ios.yml`) |
+| `xcbeautify.rb` | 3.2.1 | [homebrew-core](https://github.com/Homebrew/homebrew-core) @ `f2e343d17882` | iOS e2e + macOS e2e (`tests_e2e_other.yml`) |
+
+**Workflow install** — both workflows call `.github/workflows/scripts/install-homebrew-rnfb.sh` (from repo root). Homebrew 6+ refuses bare `brew install --formula path/to.rb`; the script copies formulae into a local `invertase/rnfb` tap, trusts it once per job, then installs:
+
+```bash
+# iOS e2e (tests_e2e_ios.yml)
+bash .github/workflows/scripts/install-homebrew-rnfb.sh applesimutils xcbeautify
+
+# macOS e2e (tests_e2e_other.yml)
+bash .github/workflows/scripts/install-homebrew-rnfb.sh xcbeautify
+```
+
+**Why** — Third-party taps can change formula definitions on every `brew update`. Vendoring avoids supply-chain drift and Brew 6 untrusted-tap warnings for live third-party taps. We still `brew trust invertase/rnfb` for the ephemeral local tap copy each job creates. The install script **uninstalls any existing `homebrew-core` (or other tap) install** of the same formula name first — GHA macOS images often preinstall `xcbeautify`, and Brew refuses same-name formulae from two taps.
+
+#### When to update a pinned formula
+
+- CI **Install brew utilities** fails after a macOS runner / Xcode image bump (common for `xcbeautify` Swift/`on_sequoia` conditionals).
+- You need a newer **applesimutils** or **xcbeautify** feature or bugfix.
+- A security advisory affects the pinned upstream release (bump `url` / version and checksums).
+
+#### How to update a pinned formula
+
+1. **Fetch the upstream formula** you want to vendor (usually `master`, or a specific commit if you need a known-good revision):
+
+   ```bash
+   # applesimutils (wix tap)
+   curl -fsSL "https://raw.githubusercontent.com/wix/homebrew-brew/master/Formula/applesimutils.rb" \
+     -o /tmp/applesimutils.rb
+
+   # xcbeautify (homebrew-core)
+   curl -fsSL "https://raw.githubusercontent.com/Homebrew/homebrew-core/master/Formula/x/xcbeautify.rb" \
+     -o /tmp/xcbeautify.rb
+   ```
+
+2. **Record the upstream commit** (for the table above and the file header):
+
+   ```bash
+   # applesimutils
+   gh api repos/wix/homebrew-brew/commits \
+     -f path=Formula/applesimutils.rb -f per_page=1 \
+     --jq '.[0].sha[:12]'
+
+   # xcbeautify
+   gh api repos/Homebrew/homebrew-core/commits \
+     -f path=Formula/x/xcbeautify.rb -f per_page=1 \
+     --jq '.[0].sha[:12]'
+   ```
+
+3. **Merge into `.github/homebrew-rnfb/Formula/<name>.rb`** — keep the RNFB header at the top (replace version + commit), then paste the upstream `class` body. Remove `head "..."` lines if present (frozen vendored formulae should not track moving branches). Example header:
+
+   ```ruby
+   # frozen_string_literal: true
+   # RNFB CI vendored formula — do not install from third-party taps in workflows.
+   # Upstream: wix/homebrew-brew @ <12-char-sha> — AppleSimulatorUtils <version>
+   # Update: see okf-bundle/ci-workflows/ios.md#pinned-homebrew-utilities
+   ```
+
+4. **Verify locally on macOS** (from repo root):
+
+   ```bash
+   bash .github/workflows/scripts/install-homebrew-rnfb.sh <name>
+   <name> --version    # xcbeautify
+   applesimutils --help # applesimutils (no --version)
+   ```
+
+   If upgrading a formula already in your Cellar, uninstall first: `brew uninstall <name>`.
+
+5. **Update this doc** — bump the version and upstream-commit columns in the table above.
+
+6. **Open a PR** — CI will exercise the same install script as production workflows. Watch the **Install brew utilities** step timing (`applesimutils` often builds from source on `macos-26`).
+
+#### Local dev (optional)
+
+Match CI with the install script, or install a single formula file via the script:
+
+```bash
+bash .github/workflows/scripts/install-homebrew-rnfb.sh applesimutils xcbeautify
+```
+
+See also `CONTRIBUTING.md` and `tests/README.md`.
+
+**`applesimutils` on modern runners** — upstream bottles target older macOS releases; GHA `macos-26` typically **builds from source** (needs Xcode). Expect a longer “Install brew utilities” step than `xcbeautify`, which usually installs from a matching bottle.

tests/README.md

@@ -13,11 +13,10 @@ Our tests are powered by [Jet ✈️](https://github.com/invertase/jet).
   - [Apple Sim Utils](https://github.com/wix/AppleSimulatorUtils):
 
     ```bash
-    brew tap wix/brew
-    brew install wix/brew/applesimutils
+    bash .github/workflows/scripts/install-homebrew-rnfb.sh applesimutils
     ```
 
-> **Note**: If Homebrew complains about a conflict in the `wix/brew` tap, run `brew untap wix/brew && brew tap wix/brew` and try installing again
+    CI uses the same vendored formulae (see `okf-bundle/ci-workflows/ios.md#pinned-homebrew-utilities`).
 
 ---