An npm to pnpm migration needs five CI changes: install pnpm at a pinned version, replace npm ci with a frozen pnpm install, move registry tokens to a trusted location, review cache paths, and update any scanner or script that names npm. The pnpm install command already fails in CI when the lockfile needs an update.
The checklist
| Area | Change |
|---|---|
| Tool install | Install pnpm in the job, then let the packageManager field pick the version |
| Install command | Use pnpm install, which is frozen in CI by default |
| Auth | Do not rely on a committed .npmrc with token placeholders |
| Caches | Cache the store only where trusted jobs write it |
| Other steps | Replace npm audit, npm run wrappers and Dockerfile npm calls |
Installing pnpm and pinning its version
The pnpm CI documentation says the standalone install script needs no Node.js, and that if package.json has a packageManager or devEngines packageManager field, pnpm switches to that version on first use, so you do not pin the version in two places. It also notes that earlier versions of the page used Corepack, and that Corepack adds a shim that starts Node for every call. Whichever you choose, pin the version in package.json and review it like any dependency.
One caution: the install script is a download piped into a shell. Read is curl pipe to shell safe to run and consider fetching a pinned version and checking it, or using your platform's maintained setup action.
Frozen lockfile behavior
The pnpm documentation states that when pnpm detects CI, it switches to frozen lockfile mode automatically, and that the install fails if a lockfile is present but needs an update. Since version 11, it also fails on a lockfile written by a newer major version instead of silently rewriting it. That means an old pnpm in CI fails loudly against a lockfile from a developer's newer one. Align the versions through the packageManager field. The equivalent npm behavior is in the npm docs for npm ci: it errors when the lock and package.json disagree and never writes to either file. Compare the three styles in frozen lockfile flags compared.
Tokens and caches
Private registry tokens often sit in a project .npmrc as an environment placeholder. That pattern needs attention under pnpm. See pnpm project .npmrc tokens. Caches are a second risk, covered in who may write the pnpm store cache.
Sweep for leftovers
Search the repository for npm in workflow files, Dockerfiles, Makefiles, and package.json scripts. Anything that runs npm install will either fail without a package-lock.json or, worse, create one and ignore your pnpm lockfile. See also delete the old lockfile after a package manager switch.
Try it yourself
Click through it at your own pace, or open it full screen. Watch how a pull request gate blocks a change on a policy result, the kind of check that should run on the migration pull request itself.
Safeguard's policies and gates, with dependency scanning, can enforce that check in CI. A free scan is at gold.safeguard.sh/scan.
Quick check
Do I need Corepack for pnpm in CI?
Not necessarily. The pnpm docs describe a standalone install and note that earlier docs used Corepack. Pick one and pin the version.
What does pnpm do if the lockfile is out of date in CI?
It fails the install, per the pnpm docs, unless you explicitly allow lockfile updates.
Sources
Last reviewed: 19 October 2026.
