MSA 환경에서 JitPack으로 공통 모듈 관리하기

MSA 프로젝트에서 각 서비스마다 공통으로 사용하는 코드를 효율적으로 관리하기 위해 JitPack을 활용했습니다. 이 글에서 JitPack이 무엇인지와, 공통 모듈을 배포하고 서비스에 사용하는 방법을 정리해보려고 합니다.

---

Jitpack이란?

https://jitpack.io/

Jipack은 Git 저장소를 Maven / Gradle 의존성으로 바로 사용할 수 있게 해주는 패키지 배포 서비스이다.

 

일반적으로 공통 모듈을 여러 서비스에서 사용하려면 각 서비스에 직접 포함시키거나(코드중복), 사설 저장소를 구축해서 사용할 수 있다. 하지만 이 방식들은 모듈 변경 시 서비스 별로 동기화가 필요하거나 저장소 운영비용이 드는 단점이 있다.  

Jitpack은 이러한 문제를 Git 저장소 기반 배포라는 방식으로 해결한다.

 

Jitpack 주요 기능

Jitpack은 다음과 같은 흐름으로 동작한다.  

1. GitHub(GitLab 등)에 있는 저장소
2. 특정 대그 또는 커밋
3. 빌드 시점에 Jitpack이 직접 빌드
4. 빌드 결과를 Maven Repository 형태로 제공

즉, Git 저장소에 태그만 찍으면, 바로 의존성으로 사용할 수 있다.  

 

왜 MSA에서 JitPack을 사용했는가?

MSA 환경에서는 여러 서비스가 공통 코드를 공유하는 경우가 많다.

예를 들어,

• 공통 응답 객체 (ApiResponse, BaseEntity)
• 공통 예외 처리 (GlobalExceptionHandler, AppException, ErrorCode …)
• 공통 유틸 클래스 (PageableUtils, CursorUtils …)
• 인증/인가 관련 공통 로직 (UserRole, AuthUser… )

이 공통 모듈을 각 서비스에 직접 복사하거나, 서브 모듈로 관리하면

• 공통 코드 수정 시 모든 서비스에 반영 필요
• 서비스 간 버전 불일치
• 배포 및 관리 복잡도 증가

단점이 있다.  

 

Jitpack을 사용하면

• 공통 모듈을 하나의 저장소로 관리
• 태그 기반으로 명확한 버전 관리
• Gradle/Maven 의존성 추가만으로 즉시 사용 가능 (쉬움)

장점이 있어서 JitPack을 도입했다.  

 

공통 모듈을 jitpack으로 배포하는 방법

 

1️⃣ 공통 모듈 프로젝트 생성

먼저, 여러 서비스에서 공통으로 사용할 코드를 하나의 모듈로 분리했다.

• 공통 응답 dto
• BaseEntity
• 공통 예외 및 에러코드
• swagger 설정
• 공통 유틸 클래스

등등

 

2️⃣ JitPack 배포를 위한 Gradle 설정

JitPack은 Git 저장소를 직접 빌드하기 때문에,

build.gradle에 선언된 라이브러리의 버전이 명확하게 정의되어있어야한다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web:3.3.5'
    ...
}

버전이 명시되지 않은 의존성이 있으면,

jitPack 빌드 과정에서 실패할 수 있으므로 주의해야한다.

 

3️⃣ 공통 모듈 변경 후 버전 관리

공통 모듈에 기능을 추가하거나 코드를 수정한 경우,

반드시 버전을 증가시켜야 한다.

예) 1.0.0 → 1.0.1 , 1.0.9 → 1.1.0

 

4️⃣ Git 태그 생성 및 Push

git commit 과 push 하고,

1. git tag 1.0.7{현재 버전}
2. git push origin 1.0.7{현재버전}

하면 github tag에 올라간다.

예시)

git commit -m "release: 1.0.7"
git push

git tag 1.0.7
git push origin 1.0.7

 

5️⃣ JitPack에서 배포 확인

GitHub에 태그가 올라가면, JitPack은 해당 태그를 기준으로 공통 모듈을 빌드하고 배포한다.  

 

배포 및 빌드 상태는 아래 JitPack 페이지에서 확인할 수 있다.

해당 프로젝트의 {organization 이름}/{repository 이름} 을 검색해서 접근할 수 있다.  

 

https://jitpack.io/

예시) KokKok-dev/Tablekok-common  

 

빌드가 성공하면 해당 버전을 Gradle/ Maven 의존성으로 바로 사용할 수 있다.

 

서비스에서 JitPack 공통 모듈 사용하는 방법

 

1️⃣ JitPack Repository 추가

https://jitpack.io/

위 링크에서도 어떻게 사용하는지 방법을 알려준다.

먼저 서비스의 build.gralde에 JitPack 저장소를 추가한다.

repositories {
    mavenCentral()
    maven { url '<https://jitpack.io>' }
}

JitPack은 Maven Repository 형태로 동작하기 때문에 기존 mavenCentral() 설정과 함께 추가해주면 된다.

 

2️⃣ 공통 모듈 의존성 추가

다음으로 JitPack에 배포한 공통 모듈을 의존성으로 추가한다.

implementation 'com.github.KokKok-dev:Tablekok-common:1.0.0'

이때 사용하는 버전은 GitHub에 생성한 태그 버전과 동일해야 한다.

공통 모듈에 변경 사항이 생기면

태그 버전을 올리고, 서비스에서는 해당 버전만 변경해 적용하면 된다.

 

3️⃣ 공통 모듈 사용 예시

의존성 설정을 했으면, 공통 모듈에 정의된 클래스들을 일반 라이브러리처럼 바로 사용할 수 있다.

예시)

BaseEntity tablekok.entity 라이브러리에서 가지고 올 수 있다.

ApiResponse도 가지고 올 수 있다.

 

GlobalExceptionHandler도 가지고 올 수 있다.

 

모두 com.tablekok 패키지 하위에 정의된 것으로 그대로 사용할 수 있다.