feat: add Yarn Modern yarn install --immutable

[MikeMcC399]

• closes Use yarn --frozen-lockfile only for Yarn v1 Classic #1822

Situation

If yarn.lock is detected, the action installs using yarn --frozen-lockfile. Although this works for Yarn v1 Classic and Yarn Modern, it is deprecated for Yarn Modern and causes a warning.

Because of this, the action documentation section Yarn Modern currently advises using the install-command parameter to install Yarn Modern as a workaround.

Change

If yarn.lock is detected, examine the contents of the beginning of the lockfile. Yarn Modern lockfiles typically begin like this:

# This file is generated by running "yarn install" inside your project.
# Manual changes might be lost - proceed with caution!

__metadata:
  version: 10
  cacheKey: 10c0

If __metadata: is detected, Yarn Modern is assumed and yarn install --immutable is used. Although --immutable is set by default in CI, applying it explicitly makes the intent clearer.

There is no change to the command used to install Yarn v1 Classic, yarn --frozen-lockfile, which remains the default after yarn.lock detection, in order to avoid a breaking change for Yarn v1 Classic users.

The Yarn Modern workflows are modified to remove the install-command parameter workaround:

• example-yarn-modern.yml
• example-yarn-modern-pnp.yml

The following README sections are updated to describe the changes:

• Yarn Modern
• Yarn Plug'n'Play
• Installation

The CHANGELOG.md is updated with the expected new version v7.5.0.

Verification

Yarn Classic

Run the workflow example-yarn-classic.yml

Confirm that installation step "Test with Yarn Classic" shows the following and is successful:

/usr/local/bin/yarn --frozen-lockfile

Yarn Modern

Run the workflow example-yarn-modern.yml

Confirm that installation step "Test with Yarn Modern" shows the following and is successful:

/opt/hostedtoolcache/node/24.18.0/x64/bin/yarn install --immutable

Yarn Modern pnp

Run the workflow example-yarn-modern-pnp.yml

Confirm that installation step "Test with Yarn Modern" shows the following and is successful:

/opt/hostedtoolcache/node/24.18.0/x64/bin/yarn install --immutable

Note that verification continues to use npx to test potentially the wrong version of Cypress in Yarn Modern pnp. This was described in issue #971 and is not targeted for a fix. Cypress documentation prefers the node-modules setting for Yarn Modern, and notes that pnp is not compatible with Cypress component testing.

---

Note

Low Risk
Install-path change is limited to Yarn Modern lockfiles and preserves Classic behavior; mis-detection is unlikely given the __metadata marker.

Overview
When a yarn.lock is present, the action now detects Yarn Modern by looking for __metadata: in the first bytes of the lockfile. Modern projects get yarn install --immutable by default; Yarn Classic still uses yarn --frozen-lockfile, so existing v1 behavior is unchanged.

Docs and v7.5.0 changelog describe the new default. Yarn Modern example workflows no longer need the install-command: yarn install workaround; the PnP example only keeps its custom command for running Cypress.

^{Reviewed by Cursor Bugbot for commit 1515e84. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.

[jennifer-shehane]

The 256-byte window encodes an assumption about the Yarn header length. It's correct (__metadata: lands ~byte 127), but a one-line comment explaining why 256 is sufficient might help future maintainers.

[MikeMcC399]

No longer checking only at the start, so I've removed this complication.

[MikeMcC399]

It appears that all versions of Yarn work with --frozen-lockfile

• https://classic.yarnpkg.com/en/docs/cli/install
• https://yarnpkg.com/cli/install

  For backward compatibility we offer an alias under the name of --frozen-lockfile, but it will be removed in a later release.

• https://v6.yarnpkg.com/cli/install#field-frozen-lockfile-immutable

  --frozen-lockfile, --immutable boolean

so it may be simpler and better for maintenance not to merge this PR, but instead to document that the deprecation warning from Yarn Modern can be ignored.

I'm trying to get clarification from yarnpkg/berry#7212.

Leaving in draft for the moment.

[MikeMcC399]

I'm withdrawing this PR.

• The Yarn maintainer wants to keep --immutable deprecated
• Using the contents of yarn.lock is not a reliable or documented way of determining the version of Yarn. Yarn Modern and Yarn zpm are sharing the same lockfile content
• The current instructions and examples for using Yarn Classic and Yarn Modern are reliably working at the moment
• If Yarn does at some point officially deprecate Yarn Classic, then installation support should be revisited (see also Yarn v1 Classic unsupported - deprecation is due #1819). At the moment there are still 8-10 Million downloads of Yarn Classic / week

Thanks @jennifer-shehane in any case for your review and comments!