[CI/CD] github actions를 사용해서 npm 배포 자동화하기

git petch

...

npm install

npm build

npm login

...

npm publish

 

번거로운 npm 배포 작업을 자동화하는 방법은 없을까?

github actions을 사용해서 npm publish 과정을 자동화해보자

npm package 정보 등록

package.json 정보(v9.6.5 기준)

npm 배포를 위해서는 패키지에 대한 기본 정보를 제공하는 package.json가 존재해야 한다.

그 중에서도 패키지명(name)과 버전(version)은 배포를 위한 필수 정보이다.

패키지명(name)

패키지 배포를 위해서는 필수적으로 입력해야하는 정보로 아래와 같은 몇 가지 규칙이 존재한다.

• 214자 이하여야 한다. (scoped package의 경우 scope 포함)
• scoped package가 아닌 경우 . 또는 _로 시작할 수 없다. (scoped pakage의 경우 가능)
• 대문자 x
• 이름은 URL의 일부, Command line의 인수 및 폴더 이름이 된다. 따라서 이름에는 안전하지 않은 문자를 포함할 수 없다.

아래는 공식문서에서 추가적으로 설명하는 팁이다.

• 핵심 노드 모듈과 동일한 이름을 사용하지 말자(ex. request)
• 이름에 'js' 똫는 'node'를 넣지말자. package.json 파일을 작성하기 때문에 js라고 가정하고 'engines' 필드를 사용해 엔진 지정이 가능하기 때문이다.
• 이름은 require()에 대한 인수로 사용되므로, 짧지만 모듈의 기능을 잘 담고 있어야 한다.

이름의 경우 https://www.npmjs.com/ 에서 검색해보거나, 'npm info <package-name>' 명령어로 중복 확인을 할 수 있다.

만약 이미 존재하는 패키지 인경우 아래와 같이 패키지 정보가 출력된다.

버전(version)

이름과 함께 npm publish를 위한 필수정보 중 하나로, 패키지의 버전을 의미한다. 이름과 버전을 합쳐서 고유한 식별자를 형성하며, 패키지 변경 사항은 버전 사항과 함께 제공되어야 한다. 

 

패키지명, 버전 이외에도 description, keywords, homepage, bugs, license, people fields(author, contributors) 등과 같은 다양한 정보들이 있다. 하지만 배포에 있어서는 필수정보가 아니라 하단의 레퍼런스에서 npm docs를 읽어보길 추천한다.

패키지명과 버전은 다음과 같이 name, version과 같은 attribute로 설정하면된다.

{
  "name": "<package-name>",
  "version": "<version>"
}

npm init

package.json에 관한 정보를 직접 입력해도 되지만, 간단하게 npm 명령어로 지원하고 있다.

npm init을 사용하면, 아래 사진과 같이 간단하게 패키지 정보를 입력할 수 있다.

npm 회원가입 및 로그인

npm 회원가입

npm publish를 위해 https://www.npmjs.com/ 에 회원가입을 한다.

npm login

'npm login' 명령어를 이용해서 로그인을 할 수 있다.

username, password, email 그리고 2 factor 인증을 위한 (one-time password)까지 입력하고나면 아래와 같이 로그인 완료 메세지가 뜬다.

로그인 방법은 CI/CD로 publish 하는 과정에서는 NPM_TOKEN으로 대체된다.(아래에서 설명할 예정)

로컬 환경에서 npm 배포

위 과정대로 따라왔다면, 최종적으로 npm publish 입력 시 배포가 완료된다.

CI/CD를 위한 git actions 설정

Github Actions란?

[Github] Github Actions를 이용한 CI/CD

Github Actions에 대한 내용은 이전에 정리해둔 글이 있어서 링크를 걸어두었다.

Github Actions를 이용한 CI/CD

Github Repository에서 Actions 탭을 이용하면 쉽게 workflow 생성이 가능하다.

Publish Node.js Package'라는 workflows를 이용하면 release 태그가 생성될 때, npm publish를 하는 예제 코드를 제공한다.

오른쪽 상단의 Start commit을 누르면, 작성한 파일이름과 내용으로 커밋이 추가된다.

# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages

name: Node.js Package

on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm ci
      - run: npm test

  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          registry-url: https://registry.npmjs.org/
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

하지만, 릴리즈 태그 기준으로 트리거링 하지않고, 버저닝하는 태그 기준으로 자동화를 하기위해서 코드를 아래와 같이 수정한다.

# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages

name: NPM Package Publish

on:
  push:
    tags:
      - 'v*'

jobs:
  publish-npm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          registry-url: https://registry.npmjs.org/
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

• v로 시작하는 태그가 생성될 때
• ubuntu-latest os 환경에서
• github 체크아웃 action 이용해 git checkout을 하고(actions/checkout@v3)
• github setup-node action을 이용해 node 16버전에 'https://registry.npmjs.org/' 경로로 registry를 설정한다.
• npm ci
• npm run build
• npm publish(npm_token을 이용한 배포)

github에 미리 정의된 action 사용

미리 정의된 명령어의 집합인 action을 통해, git checkout과 node setting 등과 같은 복잡한 작업을 간단하게 수행할 수 있다.

예를 들어서 actions/checkout을 사용하지 않으면, git checkout을 다음과 같이 직접 구현해야할 것이다.

• git init 명령어를 통해 작업 디렉토리를 로컬 저장소로 만든다.
• git config 명령어를 통해 각종 인증 관련 정보를 설정한다
• git fetch 명령어를 통해 원격 저장소로 부터 코드를 받아온다.
• git checkout 명령어를 통해 주(main) 브랜치로 전환한다.
• git log 명령어로 마지막 커밋(commit)의 해시값을 확인한다.

이외에도 다양한 action들이 정의되어 있는데 actions repository에서 확인할 수 있다.

GitHub Actions

npm ci (npm install과 비교)

[Node.js] npm install vs npm ci 차이점

npm ci에 관한 내용도 이전에 정리해둔 글이 있어서 설명은 링크로 대신한다.

npm token을 이용한 배포

코드의 env를 보면, NODE_AUTH_TOKEN라는 이름으로 github secrets으로 저장된 npm_token 값을 넘긴다. 

로컬에서 npm publish 시 설명한 npm login 단계가 있는데, username, email, password, 2 factor 인증과 같은 처리를 CI/CD에서 진행할 수는 없다. 따라서, npm login 대신 Access Token을 이용한다.

 

npm token은 Access Tokens > Generate New Token > Classic Token 에서 'publish' 타입으로 생성해준다.

생성한 Token을 Repository의 Settings > Secrets and variables > Action의 New repository secret을 통해 NPM_TOKEN이라는 이름의 변수로 등록하면 된다. 

태그 생성 후 배포 확인하기

아래 명령어로 버전업 커밋 및 태그를 push한다.

npm version minor
git push origin --tags

Actions 탭으로 이동하면, 현재 workflow 동작 상태를 확인할 수 있다.

job을 클릭하면 아래와 같이 세부 진행 로그도 확인이 가능하다.

npm 페이지에서 github actions를 통해  새로운 버전이 배포된 것을 확인할 수 있다.

---

reference

GitHub Actions로 npm publish 자동화하기 :: Outsider's Dev Story

GitHub Actions의 체크아웃(Checkout) 액션으로 코드 내려받기

package.json | npm Docs