디자인 토큰 자동화: GitHub Actions 기반 CI/CD 파이프라인 구축 가이드
디자이너가 피그마에서 색상 변수 하나를 수정했을 뿐인데, 이를 반영하기 위해 개발자가 코드를 수정하고 다시 빌드하여 배포하는 과정을 거치고 있나요? 수동으로 데이터를 옮기는 과정에서 발생하는 오타나 누락은 서비스의 시각적 일관성을 해칠 뿐만 아니라, 팀 전체의 생산성을 갉아먹는 주범입니다.
진정한 의미의 DesignOps는 디자인 데이터가 인간의 개입 없이 프로덕션 코드까지 흐르도록 만드는 ‘자동화 파이프라인’에서 완성됩니다. 이번 글에서는 GitHub Actions를 활용해 디자인 토큰(JSON)이 업데이트될 때마다 자동으로 Style Dictionary를 실행하고, 이를 npm 패키지나 CDN으로 배포하는 CI/CD 시스템 구축 실무를 다뤄보겠습니다.
왜 디자인 시스템에 CI/CD가 필요한가
디자인 시스템은 고정된 문서가 아니라 살아 움직이는 소프트웨어입니다. 피그마에서 정의한 변수들은 소스 코드와 동일한 위상을 가져야 하며, 따라서 코드와 동일한 수준의 버전 관리와 배포 자동화가 필요합니다.
GitHub Actions를 도입하면 디자인 데이터의 ‘진실의 단일 지점(SSOT)’을 GitHub 레포지토리로 설정할 수 있습니다. 피그마 플러그인을 통해 JSON 파일이 레포지토리에 푸시되는 순간, 파이프라인이 트리거되어 각 플랫폼(Web, iOS, Android)에 맞는 자산을 자동으로 생성합니다. 이렇게 구축된 환경에서는 개발자가 스타일 코드를 직접 건드릴 일이 사라지며, 오직 디자인 시스템의 규칙에만 의존하게 됩니다.
[💡 에디터의 실무 팁: 파이프라인을 구축할 때 디자인 토큰 전용 레포지토리를 분리하세요. 컴포넌트 라이브러리와 토큰을 분리해야 여러 프로젝트에서 공통된 스타일을 의존성으로 관리하기 훨씬 수월해집니다.]
GitHub Actions 워크플로우 설계하기
가장 먼저 할 일은 프로젝트 루트에 .github/workflows/deploy-tokens.yml 파일을 만드는 것입니다. 이 워크플로우는 tokens/ 폴더 내의 JSON 파일이 변경될 때만 실행되도록 설정하여 불필요한 빌드 리소스 낭비를 방지해야 합니다.
아래는 Style Dictionary 빌드 후 결과물을 자동으로 커밋하거나 npm에 배포하는 기본적인 액션 구성입니다.
name: Deploy Design Tokens
on:
push:
paths:
– ‘tokens/**’ # 토큰 파일 변경 시에만 실행
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
– name: Checkout Repository
uses: actions/checkout@v4
– name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ’20’
registry-url: ‘https://registry.npmjs.org’
– name: Install Dependencies
run: npm install
– name: Build Tokens with Style Dictionary
run: npm run build # style-dictionary build 명령 실행
– name: Automated Version Bump
run: |
git config –global user.name “DesignBot”
git config –global user.email “bot@yourcompany.com”
npm version patch -m “chore: auto-bump version [skip ci]”
– name: Publish to NPM
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
이 워크플로우의 핵심은 npm version patch 과정입니다. 디자인 수정이 일어날 때마다 자동으로 패치 버전을 올리고 이를 다시 레포지토리에 반영함으로써, 해당 토큰을 사용하는 다른 프론트엔드 프로젝트들이 npm update만으로 최신 디자인을 반영할 수 있게 돕습니다.
실무 트러블슈팅: 무한 루프와 권한 이슈 해결
자동화 파이프라인을 처음 구축할 때 가장 흔히 겪는 에러는 ‘무한 루프 빌드’입니다. 액션이 빌드 결과물을 다시 레포지토리에 푸시하면, 그 푸시가 다시 액션을 트리거하여 무한히 빌드가 반복되는 상황이죠. 이를 방지하려면 커밋 메시지에 [skip ci]를 포함하거나, 위 예시처럼 특정 경로(paths) 필터를 정교하게 설정해야 합니다.
또 다른 고충은 NPM_TOKEN이나 GITHUB_TOKEN의 권한 문제입니다. 특히 조직(Organization) 단위의 레포지토리에서는 액션이 소스 코드를 수정하고 푸시할 수 있는 ‘Write’ 권한이 기본적으로 막혀 있는 경우가 많습니다. 레포지토리 설정의 Actions > General 메뉴에서 Workflow permissions를 Read and write permissions로 반드시 변경해야 자동 버전 관리가 정상 작동합니다.
[💡 에디터의 실무 팁: 자동 배포 전에 Visual Regression Test 단계를 추가해 보세요. 토큰 변경으로 인해 기존 UI가 깨지는지 미리 확인하는 과정을 넣으면 사고를 99% 방지할 수 있습니다.]
배포를 넘어 모니터링으로: 슬랙 연동의 중요성
파이프라인이 성공적으로 돌아가는 것도 중요하지만, 협업 조직 전체가 이 변화를 인지하는 것이 더 중요합니다. 디자인 토큰 배포가 성공하면 자동으로 슬랙(Slack) 채널에 알림이 가도록 설정하세요.
“방금 brand-primary 색상이 수정되어 v1.2.4 버전이 배포되었습니다.”라는 메시지 하나가 수십 명의 개발자와 디자이너 사이의 불필요한 질문을 줄여줍니다. 기술적인 자동화는 결국 원활한 소통을 위해 존재한다는 점을 잊지 마세요.
자주 묻는 질문(FAQ)
Q1. npm 배포 대신 다른 방법은 없나요? 사내 보안 정책상 npm을 쓰기 어렵다면 빌드된 CSS/JS 파일을 AWS S3나 Azure Storage에 업로드하고 CDN을 통해 참조하는 방식을 권장합니다. 이 경우에도 GitHub Actions의 aws-s3-sync 액션을 사용해 자동화가 가능합니다.
Q2. 피그마에서 수동으로 JSON을 내보내야 하나요? 아니요. ‘Figma Variables API’나 ‘Tokens Studio’ 플러그인의 GitHub 연동 기능을 사용하면, 피그마에서 [Push] 버튼만 눌러도 바로 GitHub Actions가 트리거되도록 구성할 수 있습니다.
Q3. 빌드가 실패하면 어떻게 대응하나요? 액션 설정에 on: failure 알림을 구성하세요. 주로 JSON 구문 오류(콤마 누락 등)나 권한 만료로 실패하는 경우가 많습니다. 에러 로그를 슬랙으로 즉시 전송하게 설정하면 대응 시간을 획기적으로 줄일 수 있습니다.