llm-wiki/raw/official-docs/supply-chain-gradle-vs-maven-dependency-locking.md

---
title: Dependency locking — Gradle vs Maven vs npm/pnpm 비교
source_type: official-doc
url: https://docs.gradle.org/current/userguide/dependency_locking.html
archive_url:
status: raw
confidence: high
tags: [supply-chain, dependency-locking, gradle, maven, reproducible-build, ca-skeleton, branch:feature-build-release-supply-chain-contract]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-build-release-supply-chain-contract, feature-developer-experience-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Dependency locking — Gradle vs Maven vs npm/pnpm 비교

> Layer: `raw/official-docs/` — Gradle / Maven Enforcer / npm 공식 문서의 dependency locking 관련 verbatim 발췌. ca-tmpl 의 "Gradle dependency-locking 강제" 결정의 근거 — Maven 진영에 1급 lockfile 부재가 채택 사유.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-build-release-supply-chain-contract]] | "dependency lock = Gradle dependency-locking 강제 (`gradle/locks/*.lockfile`). lock drift 시 build fail." 결정의 근거 — Gradle 측 lockfile 메커니즘 + Maven 측 부재의 대조 |
| [[raw/branch-notes/feature-developer-experience-contract]] | JDK Temurin 21 LTS 핀 + `.tool-versions` 가 lockfile 과 직교하는 toolchain reproducibility 결정의 보조 근거 |

## 컨텍스트 / 왜 저장했는지

`feature-build-release-supply-chain-contract` 결정 "dependency lock = Gradle dependency-locking 강제 (`gradle/locks/*.lockfile`). lock drift 시 build fail." 의 근거. Maven 진영에는 1급 lockfile 이 없다는 사실이 ca-tmpl 의 Gradle 선택 근거가 되므로 raw 로 보존.

## 출처 / Source

- 원본 URL:
  - Gradle dependency locking — https://docs.gradle.org/current/userguide/dependency_locking.html
  - Maven Enforcer Plugin (dependencyConvergence rule) — https://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html
  - Maven `versions:lock-snapshots` 등 — https://www.mojohaus.org/versions/versions-maven-plugin/
  - npm shrinkwrap / package-lock — https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json
  - pnpm lockfile — https://pnpm.io/git#lockfiles
- 아카이브 URL: (미수집)
- 저자 / 조직: Gradle Inc., Apache Maven Project, npm Inc., pnpm
- 발행일: 공식 문서 (지속 갱신)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

### Gradle

> [§Dynamic versions] "Using dynamic dependency versions (e.g., `1.+` or `[1.0,2.0)`)" can cause builds to break unexpectedly because exact resolved versions change over time.

> [§Dependency Locking — definition] "Dependency locking is a process where Gradle saves the resolved versions of dependencies to a lock file, ensuring that subsequent builds use the same dependency versions."

> [§lockMode STRICT] "In this mode, in addition to the validations above, dependency locking will fail if a configuration marked as _locked_ does not have lock state associated with it."

> [§--write-locks] "To generate or update the lock state, add the `--write-locks` argument while invoking whatever tasks that would trigger the locked configurations to be resolved."

> [§CI validation] When a build resolves a locked configuration, "it will use it to verify that the given configuration still resolves the same versions. A successful build indicates that the same dependencies are used by your build as stored in the lock state."

### Maven (Enforcer Plugin)

> [§dependencyConvergence] "This rule requires that dependency versions are the same everywhere in the tree. If a project has two dependencies, A and B, both depending on the same artifact, C, this rule will fail the build if A depends on one version of C and B depends on a different version of C."

> [§dependencyManagement / BOM] "You can also use the dependencyManagement element or a 'bill of materials' (BOM) to uniquely specify a single version for all transitive dependencies with the same group ID, artifact ID, and classifier."

→ Maven 공식 도구 모음에는 **Gradle dependency-locking 또는 npm package-lock.json 과 동등한 built-in lockfile 메커니즘이 없다**. dependencyConvergence 는 *enforcement* (감지) 일 뿐 lock 이 아니다.

### npm

> [§package-lock.json] "`package-lock.json` is automatically generated for any operations where npm modifies either the `node_modules` tree, or `package.json`."

> [§package-lock.json 목적] "describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SC-DL-C1 | Gradle 의 dynamic version (`1.+`, `[1.0,2.0)`) 사용은 빌드 시점에 따라 resolved version 이 바뀌어 non-deterministic build 를 유발할 수 있음 | [§Dynamic versions] "Using dynamic dependency versions (e.g., `1.+` or `[1.0,2.0)`)" can cause builds to break unexpectedly because exact resolved versions change over time. | `official-vendor-doc` | dynamic version 사용 Gradle 프로젝트 | static version 사용 시 deterministic 보장된다는 명시는 본 인용에 없음 (plugin / toolchain 별 변수 존재) |
| SC-DL-C2 | Gradle dependency locking = resolved versions 를 lockfile 에 저장하여 subsequent build 에 동일 버전 사용 강제 | [§Dependency Locking — definition] "Dependency locking is a process where Gradle saves the resolved versions of dependencies to a lock file, ensuring that subsequent builds use the same dependency versions." | `official-vendor-doc` | Gradle `dependencyLocking` 활성화 configuration | transitive plugin 또는 buildSrc 까지 자동 lock 된다는 뜻은 아님 — `lockAllConfigurations()` 등 별도 설정 필요 |
| SC-DL-C3 | Gradle `lockMode STRICT` 는 locked configuration 에 lock state 가 없으면 build fail | [§lockMode STRICT] "In this mode, in addition to the validations above, dependency locking will fail if a configuration marked as _locked_ does not have lock state associated with it." | `official-vendor-doc` | STRICT mode 설정된 Gradle 프로젝트 | DEFAULT / LENIENT mode 의 fail-fast 동작은 본 인용 범위 밖 |
| SC-DL-C4 | Gradle lockfile 생성/갱신은 `--write-locks` 인자로 trigger | [§--write-locks] "To generate or update the lock state, add the `--write-locks` argument while invoking whatever tasks that would trigger the locked configurations to be resolved." | `official-vendor-doc` | Gradle CLI invocation | CI 에서 자동으로 lock 을 update 해야 한다는 권장은 아님 — 보통 dev local 에서 write, CI 에서 verify |
| SC-DL-C5 | Gradle CI 검증 동작 = 동일 versions 로 resolve 되는지 verify; 성공 = lock state 와 일치 | [§CI validation] "it will use it to verify that the given configuration still resolves the same versions. A successful build indicates that the same dependencies are used by your build as stored in the lock state." | `official-vendor-doc` | Gradle CI build (write-locks 없는 모드) | "lock drift 시 build fail" 의 정확한 출력 형식은 본 인용에 없음 — STRICT 모드 결합 필요 |
| SC-DL-C6 | Maven Enforcer 의 `dependencyConvergence` 는 같은 artifact 의 transitive 버전 충돌 시 build fail. lock 이 아니라 *enforcement* (감지) | [§dependencyConvergence] "This rule requires that dependency versions are the same everywhere in the tree. … this rule will fail the build if A depends on one version of C and B depends on a different version of C." | `official-vendor-doc` | Maven Enforcer Plugin 사용 프로젝트 | dependencyConvergence 가 reproducibility 를 lockfile 수준으로 보장한다는 뜻 아님 — 단일 build 내 충돌 검사일 뿐 |
| SC-DL-C7 | Maven 의 transitive 버전 관리 대안은 `dependencyManagement` element 또는 BOM (Bill of Materials) — central version 지정 | [§dependencyManagement / BOM] "You can also use the dependencyManagement element or a 'bill of materials' (BOM) to uniquely specify a single version for all transitive dependencies with the same group ID, artifact ID, and classifier." | `official-vendor-doc` | Maven 프로젝트의 transitive 버전 관리 | dependencyManagement 가 Gradle/npm lockfile 동등 보장이라는 뜻 아님 — explicit version 핀일 뿐 |
| SC-DL-C8 | npm `package-lock.json` 은 npm 이 `node_modules` 또는 `package.json` 수정 시 자동 생성 | [§package-lock.json] "`package-lock.json` is automatically generated for any operations where npm modifies either the `node_modules` tree, or `package.json`." | `official-vendor-doc` | npm v7+ 프로젝트 | yarn / pnpm lockfile 의 동등 동작 보장 아님 (별도 도구) |
| SC-DL-C9 | `package-lock.json` 목적 = 동일 tree 재현성. subsequent installs 가 intermediate dependency updates 무관 동일 tree 생성 | [§package-lock.json 목적] "describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates." | `official-vendor-doc` | npm install 재현성 | OS / Node.js version 차이로 인한 native module 차이까지 lock 한다는 뜻은 아님 |

### Strength 근거

모두 `official-vendor-doc` — Gradle Inc. / Apache Maven Project / npm Inc. 의 공식 문서. 표준 (RFC 등) 은 아니지만 각 build tool 의 정의 출처.

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `SC-DL-C1` ~ `C5`: Gradle dependency locking 의 정확한 메커니즘 (정의, STRICT mode, write-locks, CI 검증)
  - `SC-DL-C6` ~ `C7`: Maven 의 transitive 버전 대안 (Enforcer dependencyConvergence + dependencyManagement/BOM) 의 성격 (lockfile 아님)
  - `SC-DL-C8` ~ `C9`: npm package-lock.json 의 자동 생성 + 재현성 목적
- **이 자료가 증명하지 않는 것**:
  - "Maven 진영에 1급 lockfile 이 없다" 는 ca-tmpl 측 평가 결론 — 공식 Apache Maven 문서가 "lockfile 부재" 를 명시 부인하지 않음. WebFetch 응답이 "Maven does not have a built-in lockfile equivalent" 로 추론 정리한 부분은 1차 출처 인용 아님. 본 자료는 dependencyConvergence + dependencyManagement 의 성격만 직접 인용
  - pnpm / yarn lockfile 의 정확한 동작 (별도 공식 문서 참조 필요)
  - Gradle plugin 버전 / Gradle Wrapper / toolchain (JDK 버전) 까지 lock 되는지 (별도 결합 설정 필요)
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl `gradle/locks/*.lockfile` 가 실제로 `lockMode STRICT` 인지 설정 확인
  - CI 에서 `--write-locks` 없이 build 가 fail-fast 하는지 (dev workflow 분리)
  - `.tool-versions` + `gradle/wrapper/gradle-wrapper.properties` 와 결합되는 toolchain pin 의 reproducibility 영향

## 메모 / Notes (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- Gradle: `dependencyLocking { lockAllConfigurations() }` + `--write-locks` 로 lockfile 생성. CI 는 `--no-write-locks` (or 환경별 기본값) 로 drift 검출.
- Maven: dependencyManagement + Enforcer 로 부분 대응. 단, transitive lock 은 없음. 이는 reproducibility 에 약한 보장 → ca-tmpl 의 Gradle 선택을 정당화.
- npm/pnpm: lockfile 이 1급. 단, Java 진영과 직접 비교는 의미 제한적 (resolver 모델이 다름).
- ca-tmpl 결정 "SemVer + git sha suffix" 는 lockfile 과 직교. lockfile 이 reproducibility 를 보장하고, version naming 이 traceability 를 보장.
- 함정: dependency-locking 이 있어도 plugin 버전과 toolchain 은 별도 핀이 필요. `.tool-versions` / `gradle/wrapper/gradle-wrapper.properties` 핀과 함께 봐야 reproducible build 완성.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/supply-chain-slsa-provenance-framework]] (provenance 측 reproducibility 보강)
  - [[raw/official-docs/slsa-v1-provenance-schema]] (resolvedDependencies 필드)
- 인용하는 branch:
  - [[raw/branch-notes/feature-build-release-supply-chain-contract]] — Gradle dependency-locking 강제 + reproducibility 결정
  - [[raw/branch-notes/feature-developer-experience-contract]] — JDK Temurin 21 LTS 핀 + `.tool-versions`
- 인용하는 wiki:
  - [[wiki/concepts/devops-ci-supply-chain-dx]]