What is a lockfile and why CI must install the exact dependency versions

A lockfile often looks like a strange large file that only creates merge conflicts. In practice, it is one of the most important files in the project: it makes sure everyone installs the same dependencies.

Without a lockfile, or with CI ignoring it, a project can work on one developer’s machine, fail on another, and build with a third package set on the server. That is bad for debugging, testing, and security.

What a lockfile actually means

A lockfile is created by the package manager after dependency resolution. In JavaScript projects, it may be package-lock.json, pnpm-lock.yaml, or yarn.lock. Other ecosystems use different names, but the idea is similar: record the exact result of dependency selection.

A manifest file such as package.json describes what the project wants. It often contains a version range, allowing several compatible releases. The lockfile shows what was actually selected: exact versions, transitive dependencies, package sources, and integrity metadata.

So a lockfile is not noise. It is a snapshot of the dependency tree that the team wants to repeat.

Why CI must install those exact versions

CI is not supposed to be creative during dependency installation. Its job is to check the code. If every CI run can resolve fresh dependency versions, the build is testing not only your pull request, but also random registry changes.

The healthy flow looks like this:

• a developer intentionally updates a dependency;
• the package manager changes the manifest and lockfile;
• the pull request shows both changes;
• code review checks what actually changed;
• CI installs dependencies from the lockfile without rewriting it;
• tests and SCA verify the result.

That gives reproducibility. If the build fails, the team knows the package set did not silently change between the local machine and CI.

How it looks in a real project

For npm, the usual CI command is:

npm ci

It expects an existing package-lock.json and performs a clean install from it. If the manifest and lockfile disagree, that should be an error, not a silent fix.

For pnpm, CI commonly uses frozen install:

pnpm install --frozen-lockfile

For modern Yarn, the equivalent is:

yarn install --immutable

The point is the same: CI should not decide which versions to install. It should verify that the repository already contains a complete and consistent dependency state.

Where beginners usually get it wrong

Mistake 1: not committing the lockfile

For applications, the lockfile should usually be committed. Otherwise everyone resolves dependencies slightly differently, and CI has no stable source of truth.

Mistake 2: deleting the lockfile during a conflict

Lockfile conflicts are annoying. But deleting the file and regenerating it casually is a poor repair. It is better to update the branch, reinstall dependencies with the correct package manager, and inspect the diff.

Mistake 3: not reviewing lockfile changes

If a pull request changes one dependency but the lockfile adds many new transitive dependencies, the reviewer should notice. You do not need to read every line like a novel, but you should understand the size and direction of the change.

Mistake 4: allowing CI to rewrite the lockfile

If CI leaves a changed lockfile after install, it is signaling a problem. That build should fail or ask the developer to update the lockfile in the pull request.

Lockfile and security

A lockfile helps with more than repeatable builds. It also makes dependency scanning more precise. SCA sees concrete packages that enter the build, not just abstract version ranges.

That matters for supply chain work:

• it is easier to know which package version is in production;
• a bug or incident is easier to reproduce;
• dependency updates become visible in pull requests;
• an SBOM can describe the artifact more accurately;
• suspicious package changes do not hide behind a normal install.

A lockfile does not make a project secure by itself, but it removes a lot of randomness.

A practical team process

1. Choose one package manager for the project.
2. Commit the matching lockfile.
3. Document the local install command in the README.
4. Use strict or frozen install in CI.
5. Do not let CI automatically commit lockfile changes.
6. Review dependency diffs in pull requests.
7. Run tests and SCA after package updates.

Bottom line

A lockfile is not generated trash. It is the team’s agreement about the exact dependency set. It makes builds repeatable, CI honest, review clearer, and security checks more concrete.

Short version: the manifest says what the project wants; the lockfile says what the project actually got. CI should trust the second one and avoid inventing a new dependency tree on every run.

Official sources:

• https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json
• https://docs.npmjs.com/cli/v10/commands/npm-ci
• https://pnpm.io/cli/install
• https://yarnpkg.com/cli/install
• https://docs.deno.com/runtime/reference/cli/cache_and_lockfile/