[MSA] common-module

남순식·2026년 4월 27일

common-module GitHub Packages 배포

이번에 common-module을 GitHub Packages로 배포했다.

목적은 여러 서비스에서 반복적으로 사용하는 공통 코드를 별도 jar 라이브러리로 관리하고, 각 서비스가 Gradle dependency로 가져다 쓰게 하기 위함이다.

GitHub Packages는 Maven/Gradle 패키지 저장소 역할을 할 수 있으며, Gradle 프로젝트에서는 일반 Maven repository처럼 등록해서 사용할 수 있다. GitHub 공식 문서도 Gradle에서 GitHub Packages를 사용하려면 repository 설정과 dependency 선언을 추가해야 한다고 안내한다.
참고: GitHub Docs

배포된 모듈

implementation 'com.yeoljeong:common-module:0.0.n'

사용하는 쪽 설정

각 서비스의 build.gradle에 GitHub Packages 저장소를 추가한다.

repositories {
    mavenCentral()

    maven {
        name = "GithubPackages"
        url = uri("https://maven.pkg.github.com/10jeong/common-module")
        credentials {
            username = System.getenv("GITHUB_USERNAME")
            password = System.getenv("GITHUB_TOKEN")
        }
    }
}

그리고 dependency에 추가한다.

dependencies {
    implementation 'com.yeoljeong:common-module:0.0.n'
}

왜 토큰이 필요한가

GitHub Packages는 패키지를 다운로드하거나 배포할 때 인증이 필요하다. GitHub 공식 문서 기준으로 패키지를 다운로드하려면 read:packages, 배포하려면 write:packages 권한이 필요하다. private repository와 연결된 패키지라면 사용자 계정 자체도 해당 repository에 접근 권한이 있어야 한다. (GitHub Docs)

즉, 팀원이 common-module을 사용하려면 단순히 dependency를 적는 것만으로는 부족하다. Gradle이 GitHub Packages에서 jar를 내려받을 때 “이 사용자가 이 패키지를 읽을 권한이 있는가?”를 확인해야 하므로 토큰이 필요하다.

팀원은 로컬 환경변수에 아래 값을 등록하면 된다.

export GITHUB_USERNAME=본인_GITHUB_ID
export GITHUB_TOKEN=본인_PERSONAL_ACCESS_TOKEN

gradle.properties는 key=value 값만 읽는다

githubUsername=본인_GITHUB_ID    
githubToken=본인_PERSONAL_ACCESS_TOKE

토큰 권한은 소비자 기준으로는 최소한 아래가 필요하다.

read:packages

배포 담당자는 추가로:

write:packages

가 필요하다.

로컬 개발자가 private/internal package를 설치할 때는 보통 personal access token(classic)을 사용한다.

참고: GitHub Docs

인사이트

이 방식의 장점은 공통 코드를 복사하지 않고, 버전으로 관리할 수 있다는 점이다. 예를 들어 0.0.1, 0.0.2처럼 배포하면 각 서비스는 원하는 버전을 명시적으로 선택할 수 있다.

주의할 점은 GitHub Packages가 일반 공개 Maven Central처럼 완전히 익명 접근되는 저장소가 아니라는 점이다. 그래서 모든 팀원은 패키지를 내려받을 권한과 토큰 설정이 필요하다. 토큰은 코드에 직접 작성하지 말고 환경변수나 ~/.gradle/gradle.properties에 보관해야 한다.