Merge 844d397646 into 6044e13b5d

fix(#1027 ): Improve yarn v4+ corepack support with better error handling
This change improves the action's handling of yarn v4+ which requires corepack. Changes: - Add enableCorepackIfSupported() helper function to automatically enable corepack - Update yarn getCacheFolderPath to call corepack enable before checking yarn version - Detect corepack-related errors and provide clear, actionable error messages - Users can either enable corepack before the action or disable caching The error message now clearly explains: - The requirement for corepack with yarn v4+ - How to enable corepack: 'corepack enable' - Alternative: disable caching with 'package-manager-cache: false' - Link to GitHub issue for more context Fixes #1027 Related: https://github.com/actions/setup-node/issues/1027
2026-07-02 15:53:45 +08:00 · 2026-01-18 14:17:48 +00:00 · 2026-01-18 14:11:36 +00:00 · 2026-01-14 21:04:21 -06:00 · 2026-01-14 17:08:53 -06:00 · 2026-01-14 17:06:36 -06:00
8 changed files with 147 additions and 38 deletions
--- a/README.md
+++ b/README.md
@@ -115,7 +115,7 @@ See [action.yml](action.yml)

 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: 24
@@ -123,7 +123,7 @@ steps:
 - run: npm test
 ```

-The `node-version` input is optional. If not supplied, the node version from PATH will be used. However, it is recommended to always specify Node.js version and don't rely on the system one.
+The `node-version` input is optional. If not supplied, the node version from PATH will be used. However, it is recommended to always specify Node.js version and not rely on the system one.

 The action will first check the local cache for a semver match. If unable to find a specific version in the cache, the action will attempt to download a version of Node.js. It will pull LTS versions from [node-versions releases](https://github.com/actions/node-versions/releases) and on miss or failure will fall back to the previous behavior of downloading directly from [node dist](https://nodejs.org/dist/).

@@ -164,7 +164,7 @@ See the examples of using cache for `yarn`/`pnpm` and `cache-dependency-path` in

 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: 24
@@ -177,7 +177,7 @@ steps:

 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: 24
@@ -193,7 +193,7 @@ This behavior is controlled by the `package-manager-cache` input, which defaults

 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    package-manager-cache: false
@@ -212,7 +212,7 @@ jobs:
        node: [ 20, 22, 24 ]
    name: Node ${{ matrix.node }} sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - name: Setup node
        uses: actions/setup-node@v6
        with:
--- a/dist/cache-save/index.js
+++ b/dist/cache-save/index.js
@@ -44172,7 +44172,24 @@ exports.supportedPackageManagers = {
        name: 'yarn',
        lockFilePatterns: ['yarn.lock'],
        getCacheFolderPath: async (projectDir) => {
-            const yarnVersion = await (0, exports.getCommandOutputNotEmpty)(`yarn --version`, 'Could not retrieve version of yarn', projectDir);
+            // Try to enable corepack first if available
+            // This helps with yarn v2+ which requires corepack
+            await enableCorepackIfSupported();
+            let yarnVersion;
+            try {
+                yarnVersion = await (0, exports.getCommandOutputNotEmpty)(`yarn --version`, 'Could not retrieve version of yarn', projectDir);
+            }
+            catch (err) {
+                // Check if this is a corepack error message
+                const errorMsg = err.message;
+                if (errorMsg.includes('packageManager') &&
+                    errorMsg.includes('Corepack')) {
+                    throw new Error(`Yarn v4+ requires corepack to be enabled. Please run 'corepack enable' before using ` +
+                        `actions/setup-node with yarn, or disable caching with 'package-manager-cache: false'. ` +
+                        `See: https://github.com/actions/setup-node/issues/1027 for more information.`);
+                }
+                throw err;
+            }
            core.debug(`Consumed yarn version is ${yarnVersion} (working dir: "${projectDir || ''}")`);
            const stdOut = yarnVersion.startsWith('1.')
                ? await (0, exports.getCommandOutput)('yarn cache dir', projectDir)
@@ -44184,6 +44201,24 @@ exports.supportedPackageManagers = {
        }
    }
 };
+/**
+ * Tries to enable corepack for Node.js versions that support it (16.9+)
+ * This helps with yarn v2+ which requires corepack
+ * See: https://github.com/actions/setup-node/issues/1027
+ */
+const enableCorepackIfSupported = async () => {
+    try {
+        await exec.exec('corepack', ['enable'], {
+            ignoreReturnCode: true,
+            silent: true
+        });
+        core.debug('Corepack enabled successfully');
+    }
+    catch {
+        // Corepack not available or failed silently
+        core.debug('Corepack not available on this system');
+    }
+};
 const getCommandOutput = async (toolCommand, cwd) => {
    let { stdout, stderr, exitCode } = await exec.getExecOutput(toolCommand, undefined, { ignoreReturnCode: true, ...(cwd && { cwd }) });
    if (exitCode) {
--- a/dist/setup/index.js
+++ b/dist/setup/index.js
@@ -53810,7 +53810,24 @@ exports.supportedPackageManagers = {
        name: 'yarn',
        lockFilePatterns: ['yarn.lock'],
        getCacheFolderPath: async (projectDir) => {
-            const yarnVersion = await (0, exports.getCommandOutputNotEmpty)(`yarn --version`, 'Could not retrieve version of yarn', projectDir);
+            // Try to enable corepack first if available
+            // This helps with yarn v2+ which requires corepack
+            await enableCorepackIfSupported();
+            let yarnVersion;
+            try {
+                yarnVersion = await (0, exports.getCommandOutputNotEmpty)(`yarn --version`, 'Could not retrieve version of yarn', projectDir);
+            }
+            catch (err) {
+                // Check if this is a corepack error message
+                const errorMsg = err.message;
+                if (errorMsg.includes('packageManager') &&
+                    errorMsg.includes('Corepack')) {
+                    throw new Error(`Yarn v4+ requires corepack to be enabled. Please run 'corepack enable' before using ` +
+                        `actions/setup-node with yarn, or disable caching with 'package-manager-cache: false'. ` +
+                        `See: https://github.com/actions/setup-node/issues/1027 for more information.`);
+                }
+                throw err;
+            }
            core.debug(`Consumed yarn version is ${yarnVersion} (working dir: "${projectDir || ''}")`);
            const stdOut = yarnVersion.startsWith('1.')
                ? await (0, exports.getCommandOutput)('yarn cache dir', projectDir)
@@ -53822,6 +53839,24 @@ exports.supportedPackageManagers = {
        }
    }
 };
+/**
+ * Tries to enable corepack for Node.js versions that support it (16.9+)
+ * This helps with yarn v2+ which requires corepack
+ * See: https://github.com/actions/setup-node/issues/1027
+ */
+const enableCorepackIfSupported = async () => {
+    try {
+        await exec.exec('corepack', ['enable'], {
+            ignoreReturnCode: true,
+            silent: true
+        });
+        core.debug('Corepack enabled successfully');
+    }
+    catch {
+        // Corepack not available or failed silently
+        core.debug('Corepack not available on this system');
+    }
+};
 const getCommandOutput = async (toolCommand, cwd) => {
    let { stdout, stderr, exitCode } = await exec.getExecOutput(toolCommand, undefined, { ignoreReturnCode: true, ...(cwd && { cwd }) });
    if (exitCode) {
--- a/docs/adrs/0001-support-caching-deps-for-monorepos.md
+++ b/docs/adrs/0001-support-caching-deps-for-monorepos.md
@@ -8,7 +8,7 @@ Currently, `actions/setup-node` supports caching dependencies for Npm and Yarn p
 For the first iteration, we have decided to not support cases where `package-lock.json` / `yarn.lock` are located outside of repository root.  
 Current implementation searches the following file patterns in the repository root: `package-lock.json`, `yarn.lock` (in order of resolving priorities)

-Obviously, it made build-in caching unusable for mono-repos and repos with complex structure.  
+Obviously, it made built-in caching unusable for mono-repos and repos with complex structure.  
 We would like to revisit this decision and add customization for dependencies lock file location.

 ## Proposal
@@ -24,7 +24,7 @@ The second option looks more generic because it allows to:
 ## Decision

 Add `cache-dependency-path` input that will accept path (relative to repository root) to dependencies lock file.  
-If provided path contains wildcards, the action will search all maching files and calculate common hash like `${{ hashFiles('**/package-lock.json') }}` YAML construction does.  
+If provided path contains wildcards, the action will search all matching files and calculate common hash like `${{ hashFiles('**/package-lock.json') }}` YAML construction does.  
 The hash of provided matched files will be used as a part of cache key.

 Yaml examples:
--- a/docs/advanced-usage.md
+++ b/docs/advanced-usage.md
@@ -64,7 +64,7 @@ If `check-latest` is set to `true`, the action first checks if the cached versio

 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: '24'
@@ -82,7 +82,7 @@ See [supported version syntax](https://github.com/actions/setup-node#supported-v

 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version-file: '.nvmrc'
@@ -116,7 +116,7 @@ jobs:
    runs-on: windows-latest
    name: Node sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
@@ -137,7 +137,7 @@ jobs:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24.0.0-v8-canary' # it will install the latest v8 canary release for node 24.0.0
@@ -152,7 +152,7 @@ jobs:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24-v8-canary' # it will install the latest v8 canary release for node 24
@@ -168,7 +168,7 @@ jobs:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 'v24.0.0-v8-canary2025030537242e55ac'
@@ -188,7 +188,7 @@ jobs:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24-nightly' # it will install the latest nightly release for node 24
@@ -204,7 +204,7 @@ jobs:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24.0.0-nightly' # it will install the latest nightly release for node 24.0.0
@@ -220,7 +220,7 @@ jobs:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24.0.0-nightly202505066102159fa1'
@@ -238,7 +238,7 @@ jobs:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24.0.0-rc.4'
@@ -256,7 +256,7 @@ Yarn caching handles both Yarn Classic (v1) and Yarn Berry (v2, v3, v4+).

 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: '24'
@@ -275,7 +275,7 @@ steps:
 # NOTE: pnpm caching support requires pnpm version >= 6.10.0

 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: pnpm/action-setup@v4
  with:
    version: 10
@@ -294,7 +294,7 @@ steps:
 **Using wildcard patterns to cache dependencies**
 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: '24'
@@ -307,7 +307,7 @@ steps:
 **Using a list of file paths to cache dependencies**
 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: '24'
@@ -327,7 +327,7 @@ jobs:
  build:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      # Restore Node.js modules cache (restore-only)
      - name: Restore Node modules cache
        uses: actions/cache@v5
@@ -373,7 +373,7 @@ jobs:
            architecture: x86
    name: Node ${{ matrix.node_version }} - ${{ matrix.architecture }} on ${{ matrix.os }}
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
      - name: Setup node
        uses: actions/setup-node@v6
        with:
@@ -386,7 +386,7 @@ jobs:
 ## Publish to npmjs and GPR with npm
 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: '24.x'
@@ -406,7 +406,7 @@ steps:
 ## Publish to npmjs and GPR with yarn
 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: '24.x'
@@ -426,7 +426,7 @@ steps:
 ## Use private packages
 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: '24.x'
@@ -446,7 +446,7 @@ Below you can find a sample "Setup .yarnrc.yml" step, that is going to allow you

 ```yaml
 steps:
- uses: actions/checkout@v5
+- uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
    node-version: '24.x'
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
  "name": "setup-node",
-  "version": "6.1.1",
+  "version": "6.2.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "setup-node",
-      "version": "6.1.1",
+      "version": "6.2.0",
      "license": "MIT",
      "dependencies": {
        "@actions/cache": "^5.0.1",
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "setup-node",
-  "version": "6.1.1",
+  "version": "6.2.0",
  "private": true,
  "description": "setup node action",
  "main": "lib/setup-node.js",
--- a/src/cache-utils.ts
+++ b/src/cache-utils.ts
@@ -40,11 +40,32 @@ export const supportedPackageManagers: SupportedPackageManagers = {
    name: 'yarn',
    lockFilePatterns: ['yarn.lock'],
    getCacheFolderPath: async projectDir => {
-      const yarnVersion = await getCommandOutputNotEmpty(
-        `yarn --version`,
-        'Could not retrieve version of yarn',
-        projectDir
-      );
+      // Try to enable corepack first if available
+      // This helps with yarn v2+ which requires corepack
+      await enableCorepackIfSupported();
+
+      let yarnVersion: string;
+      try {
+        yarnVersion = await getCommandOutputNotEmpty(
+          `yarn --version`,
+          'Could not retrieve version of yarn',
+          projectDir
+        );
+      } catch (err) {
+        // Check if this is a corepack error message
+        const errorMsg = (err as Error).message;
+        if (
+          errorMsg.includes('packageManager') &&
+          errorMsg.includes('Corepack')
+        ) {
+          throw new Error(
+            `Yarn v4+ requires corepack to be enabled. Please run 'corepack enable' before using ` +
+              `actions/setup-node with yarn, or disable caching with 'package-manager-cache: false'. ` +
+              `See: https://github.com/actions/setup-node/issues/1027 for more information.`
+          );
+        }
+        throw err;
+      }

      core.debug(
        `Consumed yarn version is ${yarnVersion} (working dir: "${
@@ -66,6 +87,24 @@ export const supportedPackageManagers: SupportedPackageManagers = {
  }
 };

+/**
+ * Tries to enable corepack for Node.js versions that support it (16.9+)
+ * This helps with yarn v2+ which requires corepack
+ * See: https://github.com/actions/setup-node/issues/1027
+ */
+const enableCorepackIfSupported = async (): Promise<void> => {
+  try {
+    await exec.exec('corepack', ['enable'], {
+      ignoreReturnCode: true,
+      silent: true
+    });
+    core.debug('Corepack enabled successfully');
+  } catch {
+    // Corepack not available or failed silently
+    core.debug('Corepack not available on this system');
+  }
+};
+
 export const getCommandOutput = async (
  toolCommand: string,
  cwd?: string
Author	SHA1	Message	Date
Satishchoudhary94	a651f74f8e	Merge `844d397646` into `6044e13b5d`	2026-01-18 14:17:48 +00:00
Satishchoudhary94	844d397646	fix(#1027 ): Improve yarn v4+ corepack support with better error handling This change improves the action's handling of yarn v4+ which requires corepack. Changes: - Add enableCorepackIfSupported() helper function to automatically enable corepack - Update yarn getCacheFolderPath to call corepack enable before checking yarn version - Detect corepack-related errors and provide clear, actionable error messages - Users can either enable corepack before the action or disable caching The error message now clearly explains: - The requirement for corepack with yarn v4+ - How to enable corepack: 'corepack enable' - Alternative: disable caching with 'package-manager-cache: false' - Link to GitHub issue for more context Fixes #1027 Related: https://github.com/actions/setup-node/issues/1027	2026-01-18 14:11:36 +00:00
aparnajyothi-y	6044e13b5d	Docs: bump actions/checkout from v5 to v6 (#1468 ) * Update versions.yml * Update versions.yml * doc update * revert vesrions.yml	2026-01-14 21:04:21 -06:00
Panashe Fundira	8e494633d0	Fix README typo (#1226 )	2026-01-14 17:08:53 -06:00
Andreas Deininger	621ac41091	README.md: bump to latest released checkout version v6 (#1446 )	2026-01-14 17:06:36 -06:00