github packages로 private하게 패키지 배포하기 (+다운로드 방법)

안녕하세요 :) 지난 시간에는 공통 라이브러리의 문서화에 대해 다뤘습니다. 이번에는 공통 라이브러리를 배포해보고 install하는 방법까지 알아보도록 하겠습니다. 만약 저희 라이브러리가 public한 repository에 있었다면 간단한 명령어들로 배포가 가능했을 것입니다. 하지만 private한 repository에서 관리되고 있었기 때문에 몇단계를 더 거쳐야했습니다.

github packages

패키지 배포를 위해서는 패키지 레지스트리 서비스를 사용해야합니다. 우리가 흔히 알고 있는 npm 등이 있습니다. 이중 저희는 GitHub Packages를 이용하는 방식을 선택했습니다. GitHub Packages는 GitHub에서 제공하는 서비스로 private한 패키지를 무료로 배포할 수 있게 해주기 때문입니다. (npm은 private 배포가 유료입니다)

배포 과정

PAT(Personal Access Token) 발급

1. github 프로필 메뉴에서 settings 클릭
2. 왼쪽 메뉴 맨 아래의 Developer settings 클릭
3. Personal Access Tokens - Tokens(classic) 클릭
4. 오른쪽의 Generate New Token - Generate New Token(classic) 버튼 클릭
5. write:packages 권한 클릭 (이때 repo와 read:packages가 자동으로 선택됩니다)
6. Generate Token 버튼 클릭

그 다음은 이렇게 만들어진 PAT를 배포하고자하는 repository에 저장해줘야하는데요. 저희는 github actions로 배포했기 때문에 이 과정이 꼭 필요했습니다.

1. repository로 가서 settings 클릭
2. Secrets and variables - actions 클릭
3. new repository secret 클릭
4. 첨부된 사진처럼 저장

workflow 작성

전체적인 코드는 맨 아래에 첨부하고 지금은 설명을 하겠습니다. 저희는 github의 release tag를 적극 활용하고 싶었습니다.

utils@1.0.0이라는 tag를 생성하면 1.0.0이라는 버전으로 utils라는 패키지가 배포되기를 원했던거죠. 그래서 그에 맞는 워크플로우를 작성했습니다.

      - name: Extract Package Name and Version
        id: extract
        run: |
          TAG_NAME=${{ github.event.release.tag_name }}
          PACKAGE_NAME=$(echo $TAG_NAME | cut -d@ -f1)
          VERSION=$(echo $TAG_NAME | cut -d@ -f2)

          PACKAGE_PATH=$(find packages -type f -name "package.json" -exec grep -l "\"name\": \"${PACKAGE_NAME}\"" {} \; | head -n 1 | xargs dirname)

          echo "package_name=${PACKAGE_NAME}" >> $GITHUB_OUTPUT
          echo "version=${VERSION}" >> $GITHUB_OUTPUT
          echo "package_path=${PACKAGE_PATH}" >> $GITHUB_OUTPUT

릴리즈 태그가 생성되면 워크플로우가 시작되고 패키지 이름과 버전을 추출하여 저장합니다.

      - name: Update Package Version
        run: |
          cd ${{ steps.extract.outputs.package_path }}
          npm version ${{ steps.extract.outputs.version }} --no-git-tag-version

이후 패키지가 있는 경로로 가서 버전을 업데이트 해줍니다.

      - name: Build Package
        run: |
          yarn build

패키지를 빌드해준다음 npm config를 작성해줍니다.

      - name: Configure npm
        run: |
          echo "@{GitHub 사용자명이나 조직 이름}:registry=https://npm.pkg.github.com" > .npmrc
          echo "//npm.pkg.github.com/:_authToken=${{ secrets.PAT }}" >> .npmrc

배포하려는 패키지 경로로 가서 배포해줍니다.

      - name: Publish Package
        run: |
          cd ${{ steps.extract.outputs.package_path }}
          npm publish

패키지 다운로드 방법

이제 이렇게 배포된 패키지를 어떻게 사용할 수 있을지 궁금할겁니다. 어떤 패키지 매니저를 사용하느냐에 따라 방법이 다른데요.
공통점은 아까 만들어둔 PAT를 담은 config 파일이 필요하다는 것입니다.

pnpm이나 npm을 사용할 때

프로젝트 루트에 .npmrc 파일을 만듭니다.

@{GitHub 사용자명이나 조직 이름}:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken={PAT}

yarn 3 version 이상을 사용할 때

프로젝트 루트에서 상위 경로로 이동합니다. (프로젝트가 저장된 폴더)

cd ..

.yarnrc.yml 파일을 생성하여 아래와 같이 작성한 후 저장합니다.

npmScopes:
  {GitHub 사용자명이나 조직 이름}:
    npmRegistryServer: "https://npm.pkg.github.com"
    npmAuthToken: "PAT"

위처럼 하는 이유는 프로젝트 내의 .yarnrc.yml에 토큰을 작성할 경우 github에 올라갈 위험이 있기 때문입니다.

full code

workflow

name: Release By Tag

on:
  release:
    types: [published]

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write

    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
          registry-url: 'https://npm.pkg.github.com'
          scope: '@companyName'

      - name: Install Dependencies
        run: yarn install --frozen-lockfile

      - name: Extract Package Name and Version
        id: extract
        run: |
          TAG_NAME=${{ github.event.release.tag_name }}
          PACKAGE_NAME=$(echo $TAG_NAME | cut -d@ -f1)
          VERSION=$(echo $TAG_NAME | cut -d@ -f2)

          PACKAGE_PATH=$(find packages -type f -name "package.json" -exec grep -l "\"name\": \"@companyName/${PACKAGE_NAME}\"" {} \; | head -n 1 | xargs dirname)

          echo "package_name=${PACKAGE_NAME}" >> $GITHUB_OUTPUT
          echo "version=${VERSION}" >> $GITHUB_OUTPUT
          echo "package_path=${PACKAGE_PATH}" >> $GITHUB_OUTPUT

      - name: Update Package Version
        run: |
          cd ${{ steps.extract.outputs.package_path }}
          npm version ${{ steps.extract.outputs.version }} --no-git-tag-version

      - name: Build Package
        run: |
          yarn build

      - name: Configure npm
        run: |
          echo "@companyName:registry=https://npm.pkg.github.com" > .npmrc
          echo "//npm.pkg.github.com/:_authToken=${{ secrets.PAT }}" >> .npmrc

      - name: Publish Package
        run: |
          cd ${{ steps.extract.outputs.package_path }}
          npm publish