1. Why Submodule?
팀 프로젝트를 진행하면서, application.yml 파일 관리 때문에 꽤 골치 아픈 상황을 겪었습니다.
Spring Boot 프로젝트에서 application.yml 파일은 중요한 설정 정보를 담고 있습니다. 그런데 이 파일에는 다음과 같은 민감한 정보들이 포함되어 있곤 합니다.
- DB 접속 정보
- 외부 API 키
- 클라우드 서비스 인증 관련 설정
- 등등
문제는, 이 프로젝트가 여러 명이 협업하는 퍼블릭 레포지토리였고, 그런 정보를 실수로 커밋하면 보안 사고로 이어질 수 있다는 점이었습니다.
처음엔 .gitignore로 제외하고 로컬에서 각자 관리했는데, 그때마다 팀원들끼리 설정 파일을 따로 공유하거나, 실수로 잘못된 값을 넣어서 빌드가 안 되거나 하는 일이 반복됐습니다.
특히 로컬 개발 환경에서 테스트할 때마다 이 설정을 맞추는 게 꽤 번거로웠습니다.
이 글은 해당 문제를 해결하기 위해 git submodule을 도입해서 application.yml을 별도 private 저장소로 분리하고, 참조하는 방식으로 변경한 과정을 다뤄보려고 합니다.
2. Private Repository 생성

- 먼저 application.yml을 관리할 private repository를 생성합니다.
- 필요에 맞는 각각의 application.yml을 추가합니다.
3. Submodule 추가
Submodule을 사용할 프로젝트의 루트 디렉토리에서 다음 명령어를 입력합니다.
git submodule add {Submodule Repository의 주소}
ex) git submodule add https://github.com/everyones-lck/config.git
명령어가 잘 먹혔다면, 아래와 같이 private repo의 이름인 "config"로 디렉토리가 하나 생성되고, ".gitmodules" 파일이 생성됩니다.

이때, config 옆 "@e478bd3"은 private repo의 특정 커밋 버전을 참조한다는 뜻입니다.

그리고 ".gitmodules" 파일에는 아래와 같이 서브 모듈의 정보를 저장하고 있습니다.

4. build.gradle 설정
✅ 서브모듈의 설정 파일을 자동 복사하는 Gradle 설정
git submodule로 설정 파일을 가져왔더라도, 해당 .yml 파일이 src/main/resources 경로 안에 있어야 Spring Boot 프로젝트에서 정상적으로 읽을 수 있습니다.
하지만 submodule은 외부 디렉토리에 존재하므로, 직접 그 파일을 resources 디렉토리 아래로 복사해 주는 작업이 필요합니다.
이를 Gradle의 빌드 과정에 자동으로 포함시키면 훨씬 깔끔하고 실수도 줄일 수 있어서, build.gradle에 아래와 같은 작업을 추가해 줍니다.
// 서브모듈에서 설정 파일을 리소스 디렉토리로 복사하는 작업
tasks.register('copySecret', Copy) {
from 'config' // 서브모듈 디렉토리
include '*.yml' // yml 파일만 복사
into 'src/main/resources/privates' // 리소스 내부의 비공개 디렉토리로 복사
duplicatesStrategy = DuplicatesStrategy.INCLUDE // 중복 시 덮어쓰기 허용
}
// `processResources` 작업 전에 `copySecret`이 실행되도록 설정
tasks.named('processResources') {
duplicatesStrategy = DuplicatesStrategy.INCLUDE
dependsOn 'copySecret'
}
✅ 리소스 경로 추가 설정
복사한 설정 파일이 리소스로 인식되도록 하기 위해, sourceSets에 해당 디렉토리를 명시적으로 추가해 준다.
sourceSets {
main {
resources {
srcDirs "config" // 또는 'src/main/resources/privates' 도 가능
}
}
}
서브모듈 파일을 복사했기 때문에 복사된 경로를 꼭 .gitignore에 추가해줘야 합니다.
5. Submodule 사용법
Submodule Update
프로젝트를 진행하다 보면, application.yml 파일에 새로운 설정 값을 추가하거나 수정하는 경우가 생깁니다.
이 변경사항은 서브모듈(예: config 저장소)에서 이루어지기 때문에, 메인 프로젝트에서도 해당 변경을 반영하려면 서브모듈을 업데이트해야 합니다.


위처럼 메인 프로젝트 레포지토리와 서브모듈 레포지터리의 최신 커밋 해쉬값이 다르다면 아래 명령어로 업데이트를 해야 합니다.
git submodule update --remote
Submodule Push
마찬가지로, 서브 모듈에 새로운 설정 값을 추가하거나 수정된 값을 푸시해야 할 경우가 생깁니다.
이 때는 아래 명령어를 실행하자.
cd config // config 디렉토리에서 작업해야 함.
git add . (상황에 맞게)
git commit -m "(상황에 맞게)"
git push origin main
cd .. // 다시 메인 프로젝트로 돌아와서
git add . (상황에 맞게)
git commit -m "(상황에 맞게)"
git push origin <브랜치 명>
간단하게 설명하자면,
1. 서브모듈 디렉토리에서 add commit push
2. 메인 프로젝트 디렉토리에서 add commit push
이렇게 git submodule을 활용해서 민감한 설정 파일(application.yml)을 안전하게 관리하는 방법을 적용해 봤습니다.
- 퍼블릭 레포지토리에서 민감한 정보를 노출시키지 않으면서
- 팀원들 각자의 로컬 환경에서도 쉽게 설정을 공유하고
- 변경 사항도 명확하게 관리할 수 있게 되었죠.
마무리
설정 파일 관리 때문에 매번 수동으로 복사하거나 실수로 중요한 정보가 올라갈까 봐 걱정했던 문제들을 서브모듈로 깔끔하게 해결할 수 있었습니다.
저와 같은 고민을 하고 계시다면, 서브 모듈을 프로젝트에 한번 적용해 보세요!
작지만 확실한 개발 생산성 향상을 느끼실 수 있을 겁니다!
1. Why Submodule?
팀 프로젝트를 진행하면서, application.yml 파일 관리 때문에 꽤 골치 아픈 상황을 겪었습니다.
Spring Boot 프로젝트에서 application.yml 파일은 중요한 설정 정보를 담고 있습니다. 그런데 이 파일에는 다음과 같은 민감한 정보들이 포함되어 있곤 합니다.
- DB 접속 정보
- 외부 API 키
- 클라우드 서비스 인증 관련 설정
- 등등
문제는, 이 프로젝트가 여러 명이 협업하는 퍼블릭 레포지토리였고, 그런 정보를 실수로 커밋하면 보안 사고로 이어질 수 있다는 점이었습니다.
처음엔 .gitignore로 제외하고 로컬에서 각자 관리했는데, 그때마다 팀원들끼리 설정 파일을 따로 공유하거나, 실수로 잘못된 값을 넣어서 빌드가 안 되거나 하는 일이 반복됐습니다.
특히 로컬 개발 환경에서 테스트할 때마다 이 설정을 맞추는 게 꽤 번거로웠습니다.
이 글은 해당 문제를 해결하기 위해 git submodule을 도입해서 application.yml을 별도 private 저장소로 분리하고, 참조하는 방식으로 변경한 과정을 다뤄보려고 합니다.
2. Private Repository 생성

- 먼저 application.yml을 관리할 private repository를 생성합니다.
- 필요에 맞는 각각의 application.yml을 추가합니다.
3. Submodule 추가
Submodule을 사용할 프로젝트의 루트 디렉토리에서 다음 명령어를 입력합니다.
git submodule add {Submodule Repository의 주소}
ex) git submodule add https://github.com/everyones-lck/config.git
명령어가 잘 먹혔다면, 아래와 같이 private repo의 이름인 "config"로 디렉토리가 하나 생성되고, ".gitmodules" 파일이 생성됩니다.

이때, config 옆 "@e478bd3"은 private repo의 특정 커밋 버전을 참조한다는 뜻입니다.

그리고 ".gitmodules" 파일에는 아래와 같이 서브 모듈의 정보를 저장하고 있습니다.

4. build.gradle 설정
✅ 서브모듈의 설정 파일을 자동 복사하는 Gradle 설정
git submodule로 설정 파일을 가져왔더라도, 해당 .yml 파일이 src/main/resources 경로 안에 있어야 Spring Boot 프로젝트에서 정상적으로 읽을 수 있습니다.
하지만 submodule은 외부 디렉토리에 존재하므로, 직접 그 파일을 resources 디렉토리 아래로 복사해 주는 작업이 필요합니다.
이를 Gradle의 빌드 과정에 자동으로 포함시키면 훨씬 깔끔하고 실수도 줄일 수 있어서, build.gradle에 아래와 같은 작업을 추가해 줍니다.
// 서브모듈에서 설정 파일을 리소스 디렉토리로 복사하는 작업
tasks.register('copySecret', Copy) {
from 'config' // 서브모듈 디렉토리
include '*.yml' // yml 파일만 복사
into 'src/main/resources/privates' // 리소스 내부의 비공개 디렉토리로 복사
duplicatesStrategy = DuplicatesStrategy.INCLUDE // 중복 시 덮어쓰기 허용
}
// `processResources` 작업 전에 `copySecret`이 실행되도록 설정
tasks.named('processResources') {
duplicatesStrategy = DuplicatesStrategy.INCLUDE
dependsOn 'copySecret'
}
✅ 리소스 경로 추가 설정
복사한 설정 파일이 리소스로 인식되도록 하기 위해, sourceSets에 해당 디렉토리를 명시적으로 추가해 준다.
sourceSets {
main {
resources {
srcDirs "config" // 또는 'src/main/resources/privates' 도 가능
}
}
}
서브모듈 파일을 복사했기 때문에 복사된 경로를 꼭 .gitignore에 추가해줘야 합니다.
5. Submodule 사용법
Submodule Update
프로젝트를 진행하다 보면, application.yml 파일에 새로운 설정 값을 추가하거나 수정하는 경우가 생깁니다.
이 변경사항은 서브모듈(예: config 저장소)에서 이루어지기 때문에, 메인 프로젝트에서도 해당 변경을 반영하려면 서브모듈을 업데이트해야 합니다.


위처럼 메인 프로젝트 레포지토리와 서브모듈 레포지터리의 최신 커밋 해쉬값이 다르다면 아래 명령어로 업데이트를 해야 합니다.
git submodule update --remote
Submodule Push
마찬가지로, 서브 모듈에 새로운 설정 값을 추가하거나 수정된 값을 푸시해야 할 경우가 생깁니다.
이 때는 아래 명령어를 실행하자.
cd config // config 디렉토리에서 작업해야 함.
git add . (상황에 맞게)
git commit -m "(상황에 맞게)"
git push origin main
cd .. // 다시 메인 프로젝트로 돌아와서
git add . (상황에 맞게)
git commit -m "(상황에 맞게)"
git push origin <브랜치 명>
간단하게 설명하자면,
1. 서브모듈 디렉토리에서 add commit push
2. 메인 프로젝트 디렉토리에서 add commit push
이렇게 git submodule을 활용해서 민감한 설정 파일(application.yml)을 안전하게 관리하는 방법을 적용해 봤습니다.
- 퍼블릭 레포지토리에서 민감한 정보를 노출시키지 않으면서
- 팀원들 각자의 로컬 환경에서도 쉽게 설정을 공유하고
- 변경 사항도 명확하게 관리할 수 있게 되었죠.
마무리
설정 파일 관리 때문에 매번 수동으로 복사하거나 실수로 중요한 정보가 올라갈까 봐 걱정했던 문제들을 서브모듈로 깔끔하게 해결할 수 있었습니다.
저와 같은 고민을 하고 계시다면, 서브 모듈을 프로젝트에 한번 적용해 보세요!
작지만 확실한 개발 생산성 향상을 느끼실 수 있을 겁니다!