📌 [Android/Kotlin] Secret Gradle 플러그인, local.properties를 사용하여 Key 숨기기

프로젝트에서 api 키 값 등 중요한 정보들을 숨겨보자.

📝 local.properties 방식

먼저 local.properties 방식을 이용한 방법 부터 알아보자.

💙 local.properties 에 추가

local.properties 파일에 숨길 키값들을 넣어준다.

# key
SECRET_KEY=aaabbbcccddd

💙 build.gradle.kts (Module:app) 에 추가

1️⃣ local.properties 파일 읽기

val properties = Properties()
val localPropertiesFile = rootProject.file("local.properties")
if (localPropertiesFile.exists()) {
   properties.load(localPropertiesFile.inputStream())
}

local.properties 파일이 프로젝트 루트에 존재하는지 확인 후, 존재하면 Properties 객체에 해당 파일의 내용을 로드한다.

2️⃣ 키 값 추출하기

val secretKey: String = properties.getProperty("SECRET_KEY") ?: ""

SECRET_KEY라는 이름의 값을 가져온다.
값이 없으면 빈 문자열(””)을 사용.

3️⃣ BuildConfig에 값 주입

defaultConfig {
    buildConfigField("String", "SECRET_KEY", "\"$secretKey\"")
}

build.gradle의 defaultConfig 블록에서 buildConfigField를 사용해 SECRET_KEY라는 이름의 BuildConfig 상수를 생성.

💙 key 사용하기

val key = BuildConfig.SECRET_KEY // "abcdefg123456"

이렇게 local.properties 를 이용하여 키 값을 숨길 수 있다.

🚨 .gitignore 에 추가하는 것을 잊지말자

/local.properties

📝 Secrets Gradle 플러그인 방식

숨겨야 할 키값이 많아진다면 일일히 직접 읽어서 buildConfigField 에 주입해줘야하는 불편함이 있다.
이를 해결하기 위해 구글 공식 플러그인인 Secrets Gradle 플러그인 방식 을 사용해보자.

💙 Secrets Gradle 플러그인 추가

1️⃣ Version Catalog로 플러그인 추가 (libs.versions.toml 파일)

[versions]
secretsGradlePlugin = "2.0.1"

[libraries]
secrets-gradle-plugin = { module = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }

[plugins]
secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin"}

2️⃣ 프로젝트 수준의 build.gradle.kts 에 추가

buildscript {
    dependencies {
        classpath(libs.secrets.gradle.plugin)
    }
}

3️⃣ 모듈 수준 build.gradle.kts 추가

plugins {
    alias(libs.plugins.secrets.gradle.plugin)
}

💙 secrets.properties 파일 추가

플러그인이 자동으로 BuildConfig, Manifest에 주입 해줘서 키 값을 사용할 수 있다.
읽어오는 파일의 위치는 기본값은 프로젝트 루트의 local.properties이나, 보통 별도의 파일을 사용한다.
local.properties 가 있는 위치에 secrets.properties 파일을 생성해준다.

💙 secrets.properties 에 키 추가

secrets.properties 파일에 숨길 키값들을 넣어준다.

# key
SECRET_KEY=aaabbbcccddd

💙 모듈 수준의 build.gradle.kts 에 추가

secrets 블록 코드를 추가 해준다.

secrets {
	// 비밀 키 파일명
    propertiesFileName = "secrets.properties" 
    // 기본값
    defaultPropertiesFileName = "local.defaults.properties"
    // 빌드에 포함하지 않을 키
    ignoreList.add("keyToIgnore")
    ignoreList.add("sdk.*")
}

각 속성 설명

1. propertiesFileName

• 실제 키 값(예: API 키 등)을 저장하는 파일명을 지정. 
• 기본값: 
`"local.properties"`

→ secrets.properties 파일에서 키 값을 가져옴.

2. defaultPropertiesFileName

• 키 값의 기본값을 저장하는 파일명을 지정. 이 파일은 버전 관리(git)에 포함해도 됨.
• 예시: `defaultPropertiesFileName = "local.defaults.properties"`

→ secrets.properties가 없거나 값이 없을 때 기본값을 사용.

3. ignoreList

• secrets 파일에서 무시할 키(정규식 포함)를 지정.
예시: `
"sdk.dir"`(Android SDK 경로)은 기본적으로 무시됨.
사용법:
`ignoreList.add("keyToIgnore")`→ “keyToIgnore”라는 키는 무시
`ignoreList.add("sdk.*")`→ “sdk”로 시작하는 모든 키는 무시

💙 key 사용하기

val key = BuildConfig.SECRET_KEY // "abcdefg123456"


AndroidManifest.xml file
<meta-data android:value="${key}" />

🚨 잊지말자

1. 모듈 수준 build.gradle 파일에서 targetSdk 및 compileSdk를 34로 설정
2. .gitignore 에 추가 (secrets.properties)

문서 : https://developers.google.com/maps/documentation/android-sdk/secrets-gradle-plugin?hl=ko
https://github.com/google/secrets-gradle-plugin