[npm] Github packages로 private package 배포하기

최근 개인적으로 사용할 UI 라이브러리를 개발해서 배포할 상황이 있었습니다.

 

이 라이브러리는 제가 특정 프로젝트에 사용할 용도로 만들었기 때문에 npm registry에 public으로 배포하는 것은 적절하지 않았습니다.

그렇다고 npm registry에 private으로 배포하자니, 유료 플랜(7$)를 사용해야 해서 이 또한 선택지에서 제외했습니다.

 

그래서 github packages를 사용하여 private package로 배포하기로 결정했습니다.

 

Github packages 란?

GitHub Packages는 컨테이너 및 기타 종속성을 포함한 패키지를 호스팅 하고 관리하는 플랫폼입니다.

GitHub Packages는 소스 코드와 패키지를 한 곳에 통합하여 권한 관리 및 결제를 제공하므로 GitHub에서 소프트웨어 개발을 중앙 집중화할 수 있습니다.
 
Github packages는 public packages에 대하여 무료이고, private packages는 github 계정의 plan에 따라 일정량의 무료 storage와 데이터 전송을 제공합니다.

 

저같은 경우 Github 무료 사용자여서 500MB의 storage와 1GB의 월당 데이터 전송을 사용할 수 있습니다.

 

요금제에 따른 사용량은 아래 문서에 명시되어 있습니다.

https://docs.github.com/en/billing/concepts/product-billing/github-packages#free-use-of-github-packages

GitHub Packages billing - GitHub Docs

 

github packages는 무료지만, github packages의 registry는 npm registry를 사용할 때보다 패키지를 배포하는 쪽과 사용하는 쪽 모두 추가적인 설정이 필요합니다.

 

Github packages에 npm package 배포하기

github packages에 배포하는 방법은 사용자의 터미널에서 npm publish로 수동배포하는 방법과 github workflos을 통한 자동 배포가 있습니다.

 

보통 자동 배포를 하실 테니 자동 배포 방식으로 설명하겠습니다.

 

Github registry를 가리키도록 하기

먼저 배포할 패키지가 github registry를 가르키도록 해야 합니다.

 

여기에는 2가지 방법이 있습니다.

1. package.json의 publishConfig 필드에 github registry 명시
2. .npmrc에 github registry 명시

저 같은 경우 파일을 하나 더 추가하는 게 싫어서 1번 방법으로 진행했습니다.

# package.json
{
    ...
    "publishConfig": {
        "@runzipper:registry": "https://npm.pkg.github.com"
    },
    ...
}

이때 scope를 사용하지 않을 것이면

"registry": "https://npm.pkg.github.com"

로 작성하면 됩니다.

 

저 같은 경우 runzipper라는 organization에 포함된 프로젝트여서 스코프를 설정했습니다.

 

Github workflow 작성

배포를 자동화하기 위해 github workflow 스크립트를 작성했습니다.

 

이 스크립트의 registry-url에도 github registry의 url을 명시해 줍니다.

# .github/workflows/deploy.yml

name: Publish to github package registry

on:
  push:
    tags:
      - v*

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22.20'
          cache: 'yarn'
          registry-url: 'https://npm.pkg.github.com'

      - name: Install dependencies
        run: yarn install --immutable

      - name: Build
        run: yarn build

      - name: Publish to GitHub Packages
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

여기서 secrets.GITHUB_TOKEN은 worflow 실행 시 자동으로 생성되는 토큰입니다.

사용자가 따로 github에서 토큰을 발급받지 않아도 됩니다.

 

관련 내용은 아래 문서에서 찾을 수 있습니다.

https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#upgrading-a-workflow-that-accesses-a-registry-using-a-personal-access-token

Publishing and installing a package with GitHub Actions - GitHub Docs

 

workflow 트리거하기

위에 작성한 workflow를 트리거하면 github의 클라우드에서 패키지가 빌드 후 배포됩니다.

 

저는 tag가 push 되면 트리거 되는 것을 조건으로 설정했으므로 태그를 업데이트 후 푸시합니다.

npm version patch

git push origin --tags

 

Github packages에 배포돼있는 패키지 다운로드 하기

github packages에 배포돼있는 패키지를 사용하는것은 배포하는 것보다 까다롭습니다. (저는 개인적으로 그렇게 느꼈습니다.😅)

 

Github token 발급하기

배포 때와는 달리 라이브러리를 다운로드 할 때는 github personal token이 필요합니다.

github developer setting에 들어가 personal token을 발급받아 한쪽에 잘 기억해둡시다.

 

발급할 때 read:packages 권한은 반드시 체크해야합니다.

 

Github token 환경변수에 등록하기

나중에 token을 패키지 매니저의 설정파일(.npmrc, yarnrc 등)에 넣어야하는데 여기에 하드코딩하여 코드를 github에 푸시하면 그대로 토큰이 노출됩니다.

 

그래서 저는 토큰 유출을 막기위해 토큰을 쉘의 환경변수로 등록하여 사용했습니다.

# zsh를 사용할 경우
echo 'export GITHUB_TOKEN="value"' >> ~/.zshrc
source ~/.zshrc

# bash를 사용할 경우
echo 'export GITHUB_TOKEN="value"' >> ~/.bashrc
source ~/.bashrc

 

Github registry 가르키기

제일먼저 배포할 때와 마찬가지로 Github registry를 가르켜야합니다.

 

Github registry를 가르키지 않고 패키지 설치 명령어를 실행하면 패키지를 찾을 수 없다고 나옵니다.

저희 패키지는 npm registry가 아닌 github registry에 있으니 당연합니다.

 

사용하는 패키지매니저의 설정파일에 registry의 url과 앞서 환경변수에 등록해놨던 토큰의 키(GITHUB_TOKEN)를 작성합니다.

# .yarnrc.yml
npmScopes:
  "runzipper":
    npmRegistryServer: 'https://npm.pkg.github.com'
    npmAuthToken: '${GITHUB_TOKEN}'
    
# .npmrc
@runzipper:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

 

패키지 다운로드 하기

패키지 매니저에 따른 명령어를 입력해 패키지를 다운로드 합니다.

yarn add <package>

 

후기

처음 github packages에 배포해봤는데 설정에 생각보다 시간이 많이 걸렸습니다.

 

배포된 라이브러리를 실제로 다른 프로젝트에서 돌아가는지 테스트하고, 고치고, 다시 배포하는 것이 생각보다 시간을 많이 잡아먹었습니다.

 

배포된 라이브러리가 실행되는지 테스트하는데 든 생각은, "나만 사용할 라이브러리이고 한 프로젝트에 종속적이라면 private package에 배포할 필요가 있을까? 수정하고 재배포하는 시간이 개발하는 시간보다 더 드는 것 같은데?" 였습니다.

 

제가 UI 부분을 라이브러리화 한게 UI와 비즈니스 로직 패키지로 분리하고 싶어서 였습니다. 근데 그 방식이 굳이 라이브러리로 배포하는것이 아니어도 괜찮지 않나 싶습니다.

 

이런 케이스 때문에 모노레포가 등장한것 같습니다.