Use a manifest file to declare direct dependencies, then generate a lockfile and commit both files to source control. The manifest captures what the project intentionally uses, while the lockfile records the exact versions of direct and transitive packages. That combination makes builds reproducible, keeps tested code aligned with deployed code, and reduces surprises when libraries are updated.
Why dependency drift happens when teams treat manifests and installed state as the same thing
Dependency drift usually starts when development, CI, and production all resolve packages slightly differently. A manifest says what the project intends to use, but it does not guarantee the same transitive tree on every machine. The lockfile closes that gap by recording the exact resolved graph, so the build system can reproduce what was actually tested rather than recomputing a fresh version set on each run.
This matters because “works on my machine” is often a dependency-resolution problem, not a code problem. If one environment pulls a newer transitive package, the application can change behaviour, gain an unexpected vulnerability, or fail only after deployment. The core control is consistency: the same declared inputs should produce the same installed result, regardless of where the build runs.
What the manifest and lockfile each control in the dependency lifecycle
The manifest should describe intent: direct packages, version ranges where appropriate, and any policy the team wants to express explicitly. The lockfile should describe reality: the exact versions, hashes, and dependency graph that were resolved during a known-good build. Keeping both files in source control gives reviewers a clear separation between what the project asks for and what it is actually using.
That separation also improves change review. A manifest change signals an intentional upgrade or new dependency, while a lockfile-only change often means the resolver or an upstream package changed the tree. Teams should treat that distinction as meaningful, because it helps isolate whether drift came from an application decision, a transitive update, or a tooling change in the package manager. For broader supply-chain hygiene, OpenSSF is a useful reference point for open source security practices.
In practice, the most stable workflow is to update dependencies deliberately, regenerate the lockfile in a controlled step, and commit both artifacts together. That keeps development, CI, and production aligned on the same dependency state rather than allowing each stage to resolve its own version set.
How to prevent version drift without slowing delivery
Preventing drift is less about blocking updates and more about making updates explicit and repeatable. Pinning direct dependencies in the manifest, using a lockfile for all resolved packages, and installing in a mode that respects the lockfile are the basic guardrails. CI should fail if the lockfile is missing, stale, or incompatible with the manifest, because that usually means the build is no longer reproducible.
Teams should also standardise the package manager and its version, because different resolvers can produce different trees from the same manifest. This is especially important in monorepos, multi-service systems, and long-lived CI pipelines where small tooling differences create hard-to-debug drift. If production builds are generated from source, the build process itself should be the source of truth, not an ad hoc rebuild on the target host.
For security-sensitive environments, dependency drift can be more than an engineering nuisance. A package that is tested in one version and deployed in another can change its attack surface, expose a new vulnerability, or alter authentication and network behaviour. Supply-chain controls become stronger when the team can prove exactly what version set was reviewed and deployed. The NIST SSDF (SP 800-218) is a useful companion when teams want to connect dependency control to secure build practice.
What good governance looks like in CI and production
Good governance means the build pipeline enforces the contract, rather than relying on memory or convention. CI should install from the lockfile, compare the committed lockfile with the manifest, and make any dependency update pass through code review like any other production change. Production images or deployment artifacts should be created from the same locked inputs used in CI so that test and release are aligned.
Teams should also keep evidence that the lockfile was generated from a trusted build process and that dependency updates were intentional. That evidence can be a clean diff, a signed build artifact, or a change record that ties the dependency update to a specific release. If the organisation uses a formal control baseline, NIST SP 800-53 Rev 5 Security and Privacy Controls provides a control vocabulary for configuration management, access control, and integrity verification.
Risk and Threat Considerations
Version drift creates a quiet supply-chain risk because the code you reviewed is not always the code you run. That gap can introduce unreviewed transitive dependencies, unexpected behaviour changes, and exposure to malicious or compromised packages that were not present in the tested build.
Failure mechanism: The resolver, package manager, or deployment process re-evaluates dependencies in a different environment and pulls a different version graph than the one captured during testing. That can happen through floating ranges, inconsistent tooling, or rebuilding from source without a committed lockfile.
Impact: Teams lose reproducibility, security review becomes less reliable, and a production incident can emerge from a package update rather than an application code change. In supply-chain terms, the organisation has weaker assurance that a release contains only the dependencies it intended to ship.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
SLSA, NIST SP 800-53 Rev 5, CIS Controls v8 and OWASP SAMM set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| SLSA | Supply Chain Levels for Software Artifacts | Dependency locking supports reproducible, provenance-aware builds. |
| Recommendation — Use reproducible builds and verifiable provenance for every dependency update. | ||
| NIST SP 800-53 Rev 5 | CM-2 — Baseline Configuration | Committed manifests and lockfiles define the approved dependency baseline. |
| CM-6 — Configuration Settings | Version pinning and lockfile enforcement are configuration settings that prevent drift. | |
| SI-7 — Software, Firmware, and Information Integrity | Locked dependency graphs help preserve integrity between tested and deployed code. | |
| Recommendation — Establish and maintain a controlled dependency baseline for each release. Enforce dependency configuration settings in build and deployment pipelines. Verify package integrity and block unreviewed dependency changes. | ||
| CIS Controls v8 | CIS-16 — Application Software Security | Managed dependencies and reproducible builds are core application security practices. |
| Recommendation — Control software dependencies through repeatable, reviewed release processes. | ||
| OWASP SAMM | Construction | Dependency governance is part of secure build and release practice. |
| Recommendation — Build dependency management into secure development and release activities. | ||
Practitioner Guidance
What to prioritise: Make the lockfile the enforced build input everywhere, then treat manifest changes as intentional dependency policy changes and lockfile changes as the precise artifact of resolution.
What to verify: Confirm that CI, local development, and production builds all use the same package manager version and the same lockfile semantics, especially when multiple ecosystems or nested workspaces are involved. If the deployed artifact cannot be traced back to the committed lockfile, the release is not fully reproducible.
Common mistake: Allowing developers to update manifests casually while CI or production silently resolves fresh versions. That pattern creates drift even when the application code is unchanged.
Practitioner takeaway: The goal is not to freeze every dependency forever, but to make dependency change explicit, reviewable, and repeatable so that every environment installs the same known version set.
Related resources from NHI Mgmt Group
- How should teams manage IAM configuration changes across development, staging, and production without causing outages or drift?
- How should security teams implement malware prevention across open source, CI/CD, and AI-assisted development?
- How should security teams enforce version consistency across development and CI?
- How should security teams govern open source dependencies in CI/CD pipelines?
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 27, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
