2026 Remote Mac CI: Bun + npm hybrid workspaces—lockfiles & cross-border registry matrix

Use the table as a merge gate: every row should have an owner and a value in your pipeline YAML or runbook before you scale concurrent jobs on shared Apple Silicon hosts.

Split the problem in two layers: per-job settings (npm sockets, Bun cache path, frozen installs) and per-builder admission control (how many concurrent pipelines hit the same egress IP and disk). On multi-tenant remote Mac pools, the second layer usually dominates—two “modest” jobs that each open twelve sockets can still trigger 429 storms on a shared mirror VIP. Track error codes per hour and tighten job concurrency before you micro-optimize tarball deduplication.

Bun.lockb encodes the graph Bun resolved; package-lock.json encodes npm’s arborist layout including lockfileVersion quirks. If a subdirectory must stay on npm for publishing or legacy postinstall scripts, isolate it: separate package.json root with its own lockfile and run npm ci only there, while the workspace root uses Bun. Document the boundary in README so reviewers do not “fix” drift with the wrong tool.

Acceptance checks that survive audits: (1) CI prints the Bun and npm versions from the same job metadata block. (2) Frozen installs: bun install --frozen-lockfile at root and npm ci in npm-only packages. (3) Optional dependencies: compare npm_config_platform / npm_config_arch with what Bun reports on macOS arm64 so native binaries resolve consistently.

Set these at the start of the install phase (shell or CI “env” block). Replace mirror hostnames with the endpoint your security team approved.

# Cross-border friendly registry + TLS patience (both npm and Bun read npm-style config)
export NPM_CONFIG_REGISTRY="https://registry.npmjs.org/"   # or your approved mirror URL
export NPM_CONFIG_FETCH_RETRIES="3"
export NPM_CONFIG_FETCH_RETRY_MINTIMEOUT="20000"
export NPM_CONFIG_FETCH_RETRY_MAXTIMEOUT="120000"
export NPM_CONFIG_MAXSOCKETS="12"

# Bun install cache location (helps shared warm runners; use per-job dirs on multi-tenant pools)
export BUN_INSTALL_CACHE_DIR="${CI_CACHE_DIR:-$HOME/.cache/bun}/install"

# Optional: keep npm cache next to Bun cache for hybrid jobs
export npm_config_cache="${CI_CACHE_DIR:-$HOME/.cache}/npm"

# --- Frozen installs (pick the lane that matches your authority row) ---
bun --version
bun install --frozen-lockfile

# npm-only subtree example:
# (cd packages/legacy-npm && npm ci --omit=dev)

Commit a bunfig.toml next to the root package.json when you want repo-local defaults (still no secrets in git):

# bunfig.toml (example — adjust registry)
[install]
# registry = "https://your.approved.mirror.example/npm"
frozenLockfile = true
# optional: reduce install-time script risk in CI
# ignoreScripts = true

1. Mirror URL is identical in NPM_CONFIG_REGISTRY, .npmrc committed for scopes, and bunfig.toml if you set [install].registry.
2. Private @org/* scopes use //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN} (or your vault) with read-only tokens.
3. Job-level NODE_OPTIONS=--max-old-space-size=8192 only after measuring; memory pressure plus parallel installs OOMs Mac agents before the registry times out.

Names matter more than compression: a bad key either poisons the tree with stale optional deps or thrashes the CDN on every commit.

# Example: split caches so Bun binary lock does not invalidate npm cache
- uses: actions/cache@v4
  with:
    path: ~/.bun/install/cache
    key: bun-${{ runner.os }}-${{ hashFiles('bun.lockb', 'bun.lock') }}-${{ hashFiles('**/package.json') }}
    restore-keys: |
      bun-${{ runner.os }}-${{ hashFiles('bun.lockb', 'bun.lock') }}-

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-node${{ matrix.node }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-node${{ matrix.node }}-

Wrap transport failures; exit immediately when the log shows frozen lockfile or integrity errors.

#!/usr/bin/env bash
set -euo pipefail
attempt=1 max=4 delay=2
log=bun-install-$attempt.log
while [ "$attempt" -le "$max" ]; do
  log="bun-install-${attempt}.log"
  if bun install --frozen-lockfile 2>&1 | tee "$log"; then exit 0; fi
  if grep -qiE 'frozen.?lock|lockfile|checksum|integrity|ERESOLVE' "$log"; then exit 1; fi
  sleep "$delay"; delay=$((delay * 2)); attempt=$((attempt + 1))
done
exit 1

Should developers run bun install and npm install interchangeably? No. Pick one command for day-to-day lock updates per package root; use the other only in documented maintenance windows with two-person review.

Does a faster mirror remove the need for concurrency caps? No. Mirrors still rate-limit; caps protect shared remote Mac egress and keep p95 queue time predictable.

Where do Yarn-only docs fit? If part of the monorepo still uses Yarn, treat it as a third island with its own cache key and lockfile gate—or standardize. See the Yarn Berry matrix linked above.