Description

Problem: iOS yarn cache download stalls account for 28% (~18 runs) of the 64 Setup Environment CI failures on main over 30 days (Mar 16 – Apr 16, 2026). The 610MB yarn cache downloads at 0.3-2.8 MB/s on Cirrus macOS self-hosted runners (ghcr.io/cirruslabs/macos-runner:tahoe), with tar extraction sometimes hanging for 9+ minutes until the action times out.

See INFRA-3580 for the full root cause analysis.

Investigation data:

Examined 6 iOS E2E setup failures from Apr 8-10:

iOS E2E full setup timing (Cirrus macOS runners):

iOS setup takes ~2x longer than Android (189-208s vs 103-136s) due to Ruby, Bundler, CocoaPods, and Detox on top of shared steps.

Solution — two changes:

1. restore-keys fallback — Currently the yarn cache is exact-match only. On cache miss (e.g., yarn.lock changed), it triggers a full 610MB re-download. Adding restore-keys lets yarn reuse a stale cache and only update the diff. Pattern already used by Bundler cache in the same file (line 272).

2. continue-on-error: true — If the cache download or tar extraction stalls, the job currently fails entirely. With continue-on-error, a stalled cache is skipped and yarn install --immutable runs without cache (slower but succeeds). Pattern already used by CocoaPods specs cache in the same file (line 333).

Why restore-keys is safe

The concern: could restore-keys restore a stale node_modules from main with different package versions?

No. yarn install --immutable guarantees that node_modules will exactly match yarn.lock when it finishes, regardless of cache state. The cache is just a starting point — yarn adds, removes, or changes whatever is needed to reconcile. --immutable only prevents yarn.lock modifications, not node_modules updates.

Example: main merges a PR updating package X from v1.0→v1.1. Your PR branch (not rebased) still has X@v1.0 in yarn.lock. restore-keys restores main's cache with X@v1.1. yarn install --immutable runs → installs X@v1.0 per your lockfile. Same outcome as a cold install — the lockfile is always the source of truth. Cache only affects speed, not correctness.

continue-on-error — needs team input

This makes the cache step non-blocking. If the 610MB download stalls or tar extraction hangs (actual observed failure: 9.4min hang), the step fails gracefully and yarn install --immutable runs without cache (slower ~60-90s but succeeds).

Pros: stalled cache no longer kills the job; yarn install --immutable still produces correct node_modules; pattern already used by CocoaPods specs cache.

Cons: cache failures become silent (job passes but slower); reduces visibility into cache infra problems.

This change can be removed from the PR if the team prefers cache-or-fail behavior. The restore-keys change alone still adds value.

Changelog

CHANGELOG entry: null

Related issues

Fixes: INFRA-3580 (partial — addresses iOS yarn cache download stall sub-cause)

Manual testing steps

Feature: CI resilience for yarn cache

  Scenario: Yarn cache miss uses partial match fallback
    Given yarn.lock has changed since the last cached run

    When the "Restore Yarn cache" step runs
    Then it falls back to a partial key match via restore-keys
    And yarn install only updates the diff instead of full re-download

  Scenario: Stalled cache download doesn't block the job
    Given the yarn cache download stalls on a Cirrus macOS runner

    When the "Restore Yarn cache" step times out
    Then the step is marked as failed but the job continues (continue-on-error)
    And yarn install --immutable runs without cache

Screenshots/Recordings

N/A — CI workflow changes only, no UI impact.

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards. (N/A — CI workflow YAML only, no application code changes)
• I've completed the PR template to the best of my ability
• I've included tests if applicable (N/A — CI workflow configuration, validated by CI run on this PR)
• I've documented my code using JSDoc format if applicable (N/A — CI workflow YAML, no code)
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.