🪵 1. Storybook PR Preview 및 배포하기

Storybook이란?

UI 컴포넌트와 페이지를 독립적으로 빌드하기 위한 프론트엔드 작업 환경입니다. 전체 애플리케이션을 실행하지 않고도 접근하기 어려운 상태나 예외적인 케이스를 개발하고 공유할 수 있도록 도와줍니다.

Storybook 도입 이유

이전 프로젝트에서 UI 작업을 나눠서 진행했을 때 컴포넌트에 대한 문서화를 하지 않거나, 하더라도 노션에 문서화를 해두었습니다. 그러다보니 이미 만들어진 컴포넌트가 있음에도 확인하지 못하고 똑같은 컴포넌트를 만들게 되는 현상이 발생하거나, 컴포넌트를 변경하면 문서도 수동으로 변경해줘야하는 비효율이 발생했었습니다. 이러한 상황에서 어떻게 컴포넌트들을 효율적으로 관리하고 문서화할 것인지 고민한 결과 storybook을 사용하기로 결정하였습니다.

배포 방법1. chromatic

배포 방법을 찾아보았는데 chromatic으로 배포하는 것이 가장 간단해보였고 보편적이었으나 네부캠 organization 권한 문제로 배포 불가했습니다.

배포 방법2. GitHub Pages에 배포

chromatic에 배포하는 것이 불가능해 GitHub Pages에 직접 배포하기로 결정하였습니다.

그리고 main이나 develop 브랜치에 대한 배포뿐만 아니라 vercel처럼 PR이 생성됐을 때 storybook preview를 확인할 수 있으면 좋겠다고 생각했습니다. 리뷰어들이 PR을 참고할 때 단순히 사진이나 영상을 첨부하는 것보다 컴포넌트에 대해서 큰 정보를 얻을 수 있기 때문입니다.

main/develop Storybook 배포 코드 전문

    name: Deploy Storybook Production
    
    on:
      push:
        branches:
          - main
          - develop
        paths:
          - client/**
    
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
      cancel-in-progress: true
    
    defaults:
      run:
        working-directory: ./client
    
    jobs:
      deploy:
        runs-on: ubuntu-latest
        permissions:
          contents: write
    
        steps:
          - name: Checkout
            uses: actions/checkout@v4
    
          - name: Setup pnpm
            uses: pnpm/action-setup@v3
            with:
              version: 9
              run_install: false
    
          - name: Setup Node
            uses: actions/setup-node@v4
            with:
              node-version: 20
              cache: "pnpm"
              cache-dependency-path: "./client/pnpm-lock.yaml"
    
          - name: Install dependencies
            run: pnpm install
    
          - name: Build storybook
            run: pnpm run build-storybook
    
          - name: Deploy
            uses: peaceiris/actions-gh-pages@v3
            with:
              github_token: ${{ secrets.GITHUB_TOKEN }}
              publish_dir: ./client/storybook-static
              destination_dir: ${{ github.ref == 'refs/heads/main' && 'storybook' || 'storybook-develop' }}
              keep_files: true
              commit_message: "docs: deploy storybook"
    

Storybook Preview 배포 코드 전문

    name: Deploy Storybook Preview
    
    on:
      pull_request:
        types:
          - opened
          - synchronize
          - reopened
          - closed
        branches:
          - main
          - develop
        paths:
          - client/**
    
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event.number }}
      cancel-in-progress: true
    
    defaults:
      run:
        working-directory: ./client
    
    jobs:
      deploy-preview:
        if: github.event.action != 'closed'
        runs-on: ubuntu-latest
        permissions:
          contents: write
          pull-requests: write
        steps:
          - name: Checkout
            uses: actions/checkout@v4
    
          - name: Setup pnpm
            uses: pnpm/action-setup@v3
            with:
              version: 9
              run_install: false
    
          - name: Setup Node
            uses: actions/setup-node@v4
            with:
              node-version: 20
              cache: "pnpm"
              cache-dependency-path: "./client/pnpm-lock.yaml"
    
          - name: Install dependencies
            run: pnpm install
    
          - name: Build storybook
            run: pnpm run build-storybook
    
          - name: Deploy
            uses: peaceiris/actions-gh-pages@v3
            with:
              github_token: ${{ secrets.GITHUB_TOKEN }}
              publish_dir: ./client/storybook-static
              destination_dir: storybook/preview-${{ github.event.number }}
              keep_files: true
              commit_message: "docs: deploy storybook-preview"
    
          - name: Comment Preview URL
            uses: actions/github-script@v6
            with:
              script: |
                const previewUrl = `https://${context.repo.owner}.github.io/${context.repo.repo}/storybook/preview-${context.issue.number}`
                github.rest.issues.createComment({
                  issue_number: context.issue.number,
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  body: `📚 Storybook preview deployed to: [Visit Storybook Preview](${previewUrl})`
                })
    
      cleanup-preview:
        if: github.event.action == 'closed'
        runs-on: ubuntu-latest
    
        permissions:
          contents: write
          pull-requests: write
    
        defaults:
          run:
            working-directory: .
    
        steps:
          - name: Checkout
            uses: actions/checkout@v4
            with:
              ref: gh-pages
    
          - name: Delete preview directory
            run: |
              if [ -d "storybook/preview-${{ github.event.number }}" ]; then
                git config --global user.name 'github-actions[bot]'
                git config --global user.email 'github-actions[bot]@users.noreply.github.com'
                git rm -rf "storybook/preview-${{ github.event.number }}"
                git commit -m "docs: remove storybook preview for PR #${{ github.event.number }}"
                git push origin gh-pages
              fi
    
          - name: Comment Cleanup Notification
            uses: actions/github-script@v6
            with:
              script: |
                github.rest.issues.createComment({
                  issue_number: context.issue.number,
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  body: `🧹 Storybook preview for PR #${context.issue.number} has been removed.`
                })
    

main/develop storybook 배포(storybook-ci-cd.yml)

main 브랜치, develop 브랜치에 push될 때 storybook을 배포합니다.

• main 브랜치 → ${GITHUB_PAGES_URL}/ storybook 경로에 배포
• develop 브랜치 → ${GITHUB_PAGES_URL}/ storybook-develop 경로에 배포

trigger 조건

on:
  push:
    branches:
      - main
      - develop
    paths:
      - client/**

• main 또는 develop 브랜치에 push가 있을 때 실행합니다.
• client 디렉토리 내의 변경사항이 있을 때만 실행합니다.

기본 설정

defaults:
  run:
    working-directory: ./client

• working-directory: ./client
  • 스토리북은 client 코드와 만 관련이 있으므로 모든 명령어는 ./client 디렉토리에서 실행하도록 함

작업 단계

deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write

• deploy
  • deploy라는 이름의 작업을 정의
• runs-on: ubuntu-latest
  • Ubuntu 최신 버전의 가상 환경에서 실행
• permissions
  • contents: write 배포를 위해 저장소에 쓰기 권한을 부여

1. 체크아웃

- name: Checkout
  uses: actions/checkout@v4

• uses: actions/checkout@v4
  • actions/checkout@v4 액션을 통해 저장소의 코드를 workflow 실행 환경(가상 환경)으로 복사

1. PNPM 설정

- name: Setup pnpm
  uses: pnpm/action-setup@v2
  with:
    version: 9           
    run_install: false    

• uses: pnpm/action-setup@v2
  • pnpm/action-setup@v2 액션을 통해 pnpm을 설치
• run_install: false
  • 자동 의존성 설치 비활성화
  • pnpm install 명령어를 별도 스텝으로 실행하기 위함
  • 의존성 설치 과정의 세밀한 제어 가능(패키지 캐시 등)

1. Node 설정

- name: Setup Node            
  uses: actions/setup-node@v4   
  with:                        
    node-version: 20           
    cache: "pnpm"             
    cache-dependency-path: "./client/pnpm-lock.yaml" 

• uses: actions/setup-node@v4
  • actions/setup-node@v4 액션을 통해 Node.js를 설치
• cache: "pnpm"
  • pnpm 패키지들의 캐시 기능을 사용
• cache-dependency-path: "./client/pnpm-lock.yaml"
  • ‘./client/pnpm-lock.yaml’ 파일을 확인해서
    • 캐시가 있으면 캐시된 패키지 의존성을 사용
    • 캐시가 없으면 새로운 캐시를 생성

1. 의존성 설치

- name: Install dependencies
  run: pnpm install

• run: pnpm install
  • package.json에 명시된 모든 의존성 패키지들을 설치

1. Storybook 빌드

- name: Build storybook
  run: pnpm run build-storybook

• run: pnpm run build-storybook
  • Storybook을 정적 파일로 빌드
  • client/storybook-static 디렉토리에 빌드 결과물이 생성됨

1. 배포

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}  
    publish_dir: ./client/storybook-static 
    destination_dir: ${{ github.ref == 'refs/heads/main' && 'storybook' || 'storybook-develop' }}
    keep_files: true                           
    commit_message: "docs: deploy storybook"    

• uses: peaceiris/actions-gh-pages@v3
  • 정적 웹사이트를 Github Pages로 자동 배포하는 액션
• github_token: ${{ secrets.GITHUB_TOKEN }}
  • GitHub에서 자동으로 제공하는 인증 토큰
  • 저장소에 대한 접근 권한을 얻는데 사용
• publish_dir: ./client/storybook-static
  • 스토리북 빌드 결과물이 저장된 디렉토리 경로
  • 이 디렉토리의 내용이 GitHub Pages에 배포됨
• destination_dir: ${{ github.ref == 'refs/heads/main' && 'storybook' || 'storybook-develop' }}
  • GitHub Pages에 배포될 경로
  • main 브랜치면 /storybook 에 배포
  • develop 브랜치면 /storybook-develop 에 배포
• keep_files: true
  • 기존에 배포된 파일을 유지하고 새 파일만 업데이트
  • false면 기존 파일을 모두 삭제하고 새로 배포
• commit_message: "docs: deploy storybook”
  • gh-pages 브랜치에 생성되는 커밋 메시지
  • GitHub Actions 봇의 이름으로 커밋됨

개선

1. concurrency 설정

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

• 같은 브랜치에 여러 번 빠르게 push할 때 불필요한 중복 실행을 방지합니다.
• 이전 실행중인 workflow를 자동으로 취소하고 최신 push에 대해서만 실행합니다.

1. ~~Storybook 빌드 캐싱~~

- name: Cache Storybook build
  uses: actions/cache@v3
  with:
    path: ./client/storybook-static
		key: storybook-build-${{ hashFiles('client/**/*.{js,jsx,ts,tsx,mdx,css}') }}

• 추가해봤다가 캐시 생성하는 거에만 2분이 넘게 걸려서 다시 도루묵했습니다.
• 파일 하나만 변경해도 캐시 미스이기 때문에 무의미한 캐싱이어서 사용하지 않기로 결정했습니다.

---

Preview 배포(storybook-preview-ci-cd.yml)

main 브랜치나 develop 브랜치에 PR을 생성, 수정하는 경우 preview를 생성합니다.

• gh-pages 브랜치의 /storybook/preview-${PR} 폴더 생성

pr이 닫히면(merged 또는 closed) preview는 삭제됩니다.

• gh-pages 브랜치의 /storybook/preview-${PR} 폴더를 삭제

trigger 설정

on:
  pull_request:
    types:            
      - opened        
      - synchronize  
      - reopened     
      - closed     
    branches:         
      - main
      - develop
    paths:          
      - client/**    

• PR이 처음 생성됐을 때, PR에 새로운 commit이 push될 때, 닫혔던 PR이 다시 열릴 때, PR이 merge 되거나 닫힐 때 실행합니다.
• main/develop 브랜치로 가는 PR에 대해서만 실행합니다.
• client 디렉토리 내의 변경사항이 있을 때만 실행합니다.

기본 설정

defaults:
  run:
    working-directory: ./client

• working-directory: ./client
  • 스토리북은 client 코드와만 관련이 있으므로 모든 명령어는 ./client 디렉토리에서 실행하도록 함

작업 단계 - 작업1 (deploy-preview)

  deploy-preview:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

• if: github.event.action != 'closed'
  • PR이 생성됐을 때, 새로운 commit이 push 됐을 때, 다시 열릴때만 실행.(PR이 merge 되거나 닫힐 때를 제외)
• runs-on: ubuntu-latest
  • Ubuntu 최신 버전의 가상 환경에서 실행
• contents: write
  • gh-pages 배포를 위해 저장소에 쓰기 권한을 부여
• pull-requests:write:
  • PR에 preview URL 코멘트와 배포 상태를 작성하기 위해 쓰기 권한을 부여

1~5**. 1.체크아웃 ~ 5.Storybook 빌드까지 위와 동일하다.**

1. 배포

- name: Deploy
 uses: peaceiris/actions-gh-pages@v3
 with:
   github_token: ${{ secrets.GITHUB_TOKEN }}
   publish_dir: ./client/storybook-static
   destination_dir: storybook/preview-${{ github.event.number }}
   keep_files: true
   commit_message: "docs: deploy storybook-preview

• uses: peaceiris/actions-gh-pages@v3
  • 정적 웹사이트를 Github Pages로 자동 배포하는 액션
• github_token: ${{ secrets.GITHUB_TOKEN }}
  • GitHub에서 자동으로 제공하는 인증 토큰
  • 저장소에 대한 접근 권한을 얻는데 사용
• publish_dir: ./client/storybook-static
  • 스토리북 빌드 결과물이 저장된 디렉토리 경로
  • 이 디렉토리의 내용이 GitHub Pages에 배포됨
• destination_dir: storybook/preview-${{ github.event.number }}
  • GitHub Pages에 배포될 경로
  • PR 번호를 사용하여 각 PR별 고유한 preview 경로 생성
  • 예: PR #123 → /storybook/preview-123
• keep_files: true
  • 기존에 배포된 파일을 유지하고 새 파일만 업데이트
  • false면 기존 파일을 모두 삭제하고 새로 배포
• commit_message: "docs: deploy storybook”
  • gh-pages 브랜치에 생성되는 커밋 메시지
  • GitHub Actions 봇의 이름으로 커밋됨

1. Preview URL 코멘트

- name: Comment Preview URL   
 uses: actions/github-script@v6    
 with:
   script: |
     const previewUrl = `https://${context.repo.owner}.github.io/${context.repo.repo}/storybook/preview-${context.issue.number}`
     github.rest.issues.createComment({
       issue_number: context.issue.number,  
       owner: context.repo.owner,        
       repo: context.repo.repo,          
       body: `📚 Storybook preview deployed to: [Visit Storybook Preview](${previewUrl})`  
     })

• uses: actions/github-script@v6
  • GitHub API를 JavaScript로 직접 호출할 수 있게 해주는 액션
  • PR에 코멘트를 달기 위해 사용
• github.rest.issues.createComment()
  • PR에 코멘트를 생성하는 GitHub API 호출
  • 파라미터
    • issue_number: PR 번호
    • owner: GitHub 계정/조직 이름
    • repo: 저장소 이름
    • body: 마크다운 형식의 코멘트 내용

작업 단계 - 작업2 (cleanup-preview)

  cleanup-preview:
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest

    permissions:
      contents: write
      pull-requests: write

    defaults:
      run:
        working-directory: .

• cleanup-preview
  • PR이 닫혔을 때 preview를 정리하는 job
• if: github.event.action == 'closed'
  • PR이 닫혔을 때만(closed or merged) 실행
• runs-on: ubuntu-latest
  • 최신 Ubuntu 환경에서 실행
  • GitHub Actions 실행 환경 지정
• permissions
  • contents:write 저장소 내용 수정 권한
  • pull-requests:write: PR 코멘트 작성 권한
• working-directory: .
  • 작업 디렉토리를 프로젝트 루트(.)로 설정

1. 체크아웃

- name: Checkout
 uses: actions/checkout@v4 
 with:
   ref: gh-pages 

• uses: actions/checkout@v4
  • GitHub 저장소의 코드를 가져오는 기본 액션
• ref: gh-pages
  • checkout할 브랜치를 지정
  • 기본 브랜치가 아닌 gh-pages 브랜치를 가져옴
  • GitHub Pages 배포에 사용되는 특수 브랜치

1. preview 디렉터리 삭제

- name: Delete preview directory
 run: |
   if [ -d "storybook/preview-${{ github.event.number }}" ]; then
     git config --global [user.name](http://user.name/) 'github-actions[bot]'
     git config --global user.email 'github-actions[bot]@users.noreply.github.com'
     git rm -rf "storybook/preview-${{ github.event.number }}"
     git commit -m "docs: remove storybook preview for PR #${{ github.event.number }}"
     git push origin gh-pages
   fi

• if [ -d "storybook/preview-${{ github.event.number }}" ]
  • -d: 디렉토리 존재 여부 확인
  • PR 번호로 된 preview 폴더가 있는지 체크
• git config --global user.name 'github-actions[bot]' git config --global user.email 'github-actions[bot]@users.noreply.github.com'
  • Git 사용자 설정
  • GitHub Action 봇으로 커밋하기 위한 설정
• git rm -rf "storybook/preview-${{ github.event.number }}”
  • git rm: Git에서 파일/디렉토리 삭제
  • -rf: 재귀적으로 강제 삭제
  • PR 번호에 해당하는 preview 폴더 삭제
• git commit -m "docs: remove storybook preview for PR #${{ github.event.number }}"
  • 삭제 작업을 커밋으로 기록
  • 커밋 메시지에 PR 번호 포함
• git push origin gh-pages
  • gh-pages 브랜치에 변경사항 push
  • preview 삭제 완료

1. preview URL cleanup 코멘트

-name: Comment Cleanup Notification
uses: actions/github-script@v6
with:
  script: |
    github.rest.issues.createComment({
      issue_number: context.issue.number,
      owner: context.repo.owner,
      repo: context.repo.repo,
      body: `🧹 Storybook preview for PR #${context.issue.number} has been removed.`
    })

• uses: actions/github-script@v6
  • GitHub API를 JavaScript로 직접 호출할 수 있게 해주는 액션
  • PR에 코멘트를 달기 위해 사용
• github.rest.issues.createComment()
  • PR에 코멘트를 생성하는 GitHub API 호출
  • 파라미터
    • issue_number: PR 번호
    • owner: GitHub 계정/조직 이름
    • repo: 저장소 이름
    • body: 마크다운 형식의 코멘트 내용

개선

1. concurrency 추가

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event.number }}
  cancel-in-progress: true

• 같은 PR에 대해 여러 번 빠르게 생성, 재오픈, 수정, 삭제될 때 불필요한 workflow 중복 실행을 방지합니다.
• 이전 실행중인 workflow를 자동으로 취소하고 최신 PR 생성, 재오픈, 수정, 삭제에 대한 workflow를 실행합니다.

결과

배포된 storybook

• 아직 main 브랜치에 push하지 않아서 생성되지 않았습니다. 😅

배포된 storybook-develop

storybook

배포된 storybook/prevew-${PR번호}

• PR이 merge되면 배포된 폴더가 사라져 404가 뜨게 되므로 링크는 첨부하지 않았습니다.
• 아래 사진처럼 PR을 생성하면 preview가 배포되고, PR이 merge되면 배포된 preview가 삭제됩니다.

참고 자료

https://storybook.js.org/docs

https://yogjin.tistory.com/106

수정님의 typedoc-ci-cd.yml