---
title: Renovate Gradle Manager — Official Documentation
source_type: official-doc
url: https://docs.renovatebot.com/modules/manager/gradle/
archive_url:
related_branches: [feature-build-release-supply-chain-contract]
related_projects: []
tags: [official-doc, ca-skeleton, ci-cd, gradle, build-tooling]
created: 2026-06-15
---

# Renovate Gradle Manager — Official Documentation

> Layer: `raw/official-docs/` — 외부 공식 문서의 원문 발췌·출처 기록.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수, 최소 1개+)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-build-release-supply-chain-contract]] | Decision D3 — "dependency upgrade bot = Renovate 기본"의 근거: Renovate의 Gradle 지원 범위(파일 목록, lockfile 갱신 via --write-locks, Version Catalog 지원), 및 `allowedUnsafeExecutions: ["gradleWrapper"]` supply-chain 보안 제약 |

## 출처 / Source

- 원본 URL: https://docs.renovatebot.com/modules/manager/gradle/
- 아카이브 URL:
- 저자 / 조직: Renovate (Mend)
- 발행일: (연속 갱신 문서 — 발행일 단일 표기 없음)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

`feature-build-release-supply-chain-contract` branch 의 D3 결정("dependency upgrade bot = Renovate 기본")이 `UNSUPPORTED_DECISION` 으로 분류되어 있었기 때문이다. Renovate 공식 문서에서 Gradle 파일 패턴 매칭 범위, lockfile 갱신 방식(`--write-locks`), Version Catalog(`.versions.toml`) 지원, 그리고 self-hosted 환경에서 `gradleWrapper` 실행의 supply-chain 보안 제약을 직접 확인하여 D3 결정을 근거 있는 선택으로 전환한다.

## 핵심 인용 / Key quotes (verbatim, 3~5문장)

> [§File Patterns Matched] "The Gradle manager detects dependencies in files matching these patterns:"
> `/\.gradle(\.kts)?$/`
> `/(^|/)gradle\.properties$/`
> `/(^|/)gradle/.+\.toml$/`
> `/(^|/)buildSrc/.+\.kt$/`
> `/\.versions\.toml$/`
> `/(^|/)versions.props$/`
> `/(^|/)versions.lock$/`

> [§Lockfile Support] "The manager maintains `gradle.lockfile` artifacts. During maintenance operations, it \"calls `./gradlew :dependencies --write-locks` on the root project and subprojects.\" For standard updates, the tool \"automatically updates lock state entries via the `--update-locks` command line flag.\""

> [§Gradle Wrapper Execution] "Renovate will only execute the Gradle Wrapper (via `./gradlew` or `gradlew.bat`) if the self-hosted administrator configures `allowedUnsafeExecutions` to include the `gradleWrapper` option." This requirement exists due to "possible supply chain security attack vectors that can occur with the Gradle Wrapper being executed."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| RENOV-GRAD-C1 | Renovate Gradle manager 는 `.gradle`, `.gradle.kts`, `gradle.properties`, `*.toml`(gradle/ 디렉터리), `.versions.toml`, `versions.props`, `versions.lock` 파일 패턴을 대상으로 의존성을 탐지한다 | [§File Patterns Matched] "The Gradle manager detects dependencies in files matching these patterns: `/\.gradle(\.kts)?$/`, `/(^|/)gradle\.properties$/`, `/(^|/)gradle/.+\.toml$/`, `/\.versions\.toml$/`, `/(^|/)versions.props$/`, `/(^|/)versions.lock$/`" | `official-vendor-doc` | Renovate 사용 모든 Gradle 프로젝트 (self-hosted 포함) | Gradle 외 빌드 시스템(Maven, Bazel)의 파일 패턴; 커스텀 파일 경로 지원 여부 |
| RENOV-GRAD-C2 | Renovate 는 `gradle.lockfile` 유지 시 루트 프로젝트 및 서브프로젝트에 `./gradlew :dependencies --write-locks` 를 실행한다 | [§Lockfile Support] "calls `./gradlew :dependencies --write-locks` on the root project and subprojects" | `official-vendor-doc` | Renovate 로 lockfile maintenance 를 활성화한 Gradle 프로젝트 | `gradleWrapper` 실행 허가(`allowedUnsafeExecutions`) 없이 이 동작이 가능하다는 의미가 아님(C3 참조) |
| RENOV-GRAD-C3 | self-hosted 환경에서 Renovate 가 Gradle Wrapper(`./gradlew`)를 실행하려면 관리자가 `allowedUnsafeExecutions` 에 `gradleWrapper` 옵션을 포함시켜야 한다 | [§Gradle Wrapper Execution] "Renovate will only execute the Gradle Wrapper (via `./gradlew` or `gradlew.bat`) if the self-hosted administrator configures `allowedUnsafeExecutions` to include the `gradleWrapper` option." | `official-vendor-doc` | self-hosted Renovate 인스턴스 운영자 | Renovate Cloud(app.renovatebot.com) 환경 — 관리 방식이 다를 수 있음 |
| RENOV-GRAD-C4 | `gradleWrapper` 실행 허가가 supply-chain 공격 벡터(supply chain security attack vectors)와 관련된 보안 제약이다 | [§Gradle Wrapper Execution] "possible supply chain security attack vectors that can occur with the Gradle Wrapper being executed." | `official-vendor-doc` | self-hosted 환경에서 Renovate PR 자동 머지 + lockfile 재생성을 구성할 때 | Gradle Wrapper 자체의 CVE; Renovate 외 다른 도구의 gradlew 실행 위험 |
| RENOV-GRAD-C5 | Renovate 는 일반 업데이트 시 `--update-locks` CLI 플래그를 통해 lock state 항목을 자동으로 갱신한다 | [§Lockfile Support] "automatically updates lock state entries via the `--update-locks` command line flag" | `official-vendor-doc` | Renovate 로 개별 의존성 버전 업데이트 PR 생성 시 | 전체 lockfile 재생성(`--write-locks`) 과 동일하지 않음 — 개별 항목 업데이트 전용 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `RENOV-GRAD-C1`: Renovate 가 Gradle Version Catalog(`.versions.toml`)를 포함한 Gradle 관련 파일 패턴을 공식 지원한다.
  - `RENOV-GRAD-C2`: lockfile 유지 모드에서 `--write-locks` 를 실행한다.
  - `RENOV-GRAD-C3`: self-hosted 환경에서 `allowedUnsafeExecutions: [gradleWrapper]` 설정이 필수 전제조건이다.
  - `RENOV-GRAD-C4`: 이 전제조건이 존재하는 이유가 supply-chain 보안 위협이라는 것을 Renovate 공식 문서가 명시적으로 인정한다.
  - `RENOV-GRAD-C5`: 개별 의존성 업데이트 PR 생성 시 `--update-locks` 를 사용한다.
- 이 자료가 증명하지 않는 것:
  - Renovate 가 Gradle 외 빌드 시스템(Maven, Bazel)에서 동일하게 동작한다는 것.
  - Renovate Cloud(호스팅 서비스) 환경에서 `allowedUnsafeExecutions` 가 동일하게 적용된다는 것.
  - Dependabot 대비 Renovate 의 기능 우위 — 이 문서는 Renovate 자체의 기능만 설명하며 비교 없음.
  - `gradleWrapper` 실행이 안전하다는 주장 — 오히려 반대.
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-skeleton self-hosted Renovate 인스턴스 구성 시 `allowedUnsafeExecutions: ["gradleWrapper"]` 실제 설정 위치(Renovate config 파일 또는 환경 변수) 확인 필요.
  - `gradle/locks/*.lockfile` 패턴(ca-skeleton D8) 과 Renovate 가 기대하는 `gradle.lockfile` 패턴 간 경로 충돌 여부 확인 필요.

## 메모 / Notes

- D3 업그레이드: `RENOV-GRAD-C1`~`C3` 로 D3 는 `UNSUPPORTED_DECISION` 에서 `official-vendor-doc` 뒷받침 결정으로 전환 가능.
- D3 의 "Dependabot 은 조직 표준일 때 허용" 부분은 여전히 외부 raw source 미확보 — Dependabot 공식 docs 추가 보강 권고.
- lockfile 경로 불일치 주의: D8 의 `gradle/locks/*.lockfile` vs Renovate 문서의 `gradle.lockfile` — 경로가 다를 경우 Renovate 가 lockfile 을 탐지하지 못할 수 있음. `/(^|/)versions.lock$/` 패턴과의 관계 확인 필요.
- 추가로 봐야 할 동일 출처 페이지: `https://docs.renovatebot.com/self-hosted-configuration/#allowedunsafeexecutions` (self-hosted config 레퍼런스)

## Related / 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/supply-chain-gradle-vs-maven-dependency-locking]] (D8 근거 — Gradle dependency-locking)
- 이 자료를 인용한 wiki 요약: (생성 시 추가)