zellyy-finance/docs/linear-github-connection-guide.md

Linear GitHub 연동 가이드

Linear와 GitHub 간의 기본 연결 설정 및 구성 가이드입니다.

📋 목차

• 개요
• 사전 요구사항
• 1단계: Linear API 키 생성
• 2단계: GitHub 개인 액세스 토큰 생성
• 3단계: 자동 설정 실행
• 4단계: GitHub Secrets 설정
• 5단계: Linear 웹훅 설정
• 6단계: 연동 테스트
• 문제 해결

개요

이 가이드는 Linear 프로젝트 관리 도구와 GitHub 리포지토리 간의 양방향 연동을 설정하는 방법을 설명합니다.

연동 기능

• 이슈 상태 동기화: PR 상태에 따른 Linear 이슈 상태 자동 업데이트
• 자동 코멘트: GitHub 이벤트를 Linear 이슈에 자동으로 코멘트
• 릴리즈 관리: semantic-release와 연동된 자동 릴리즈 노트 생성
• 워크플로우 자동화: GitHub Actions를 통한 완전 자동화

사전 요구사항

계정 및 권한

• Linear 계정: 워크스페이스 관리자 권한
• GitHub 계정: 리포지토리 관리자 권한
• Node.js: 18.0.0 이상

필수 파일 확인

다음 파일들이 프로젝트에 존재하는지 확인하세요:

# 자동 확인
npm run linear:setup --verify

1단계: Linear API 키 생성

1.1 Linear 설정 페이지 접근

1. Linear 워크스페이스 로그인
2. Settings → API → Personal API keys 이동

1.2 API 키 생성

1. "Create API key" 클릭
2. 키 이름: Zellyy Finance GitHub Integration
3. 권한 설정:
   • Read: Issues, Comments, Teams, Projects
   • Write: Issues, Comments (상태 업데이트 및 코멘트 생성용)

1.3 API 키 복사

• 생성된 API 키를 안전한 곳에 저장
• 형식: lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2단계: GitHub 개인 액세스 토큰 생성

2.1 GitHub 설정 페이지 접근

1. GitHub 계정 로그인
2. Settings → Developer settings → Personal access tokens → Tokens (classic) 이동

2.2 토큰 생성

1. "Generate new token" → "Generate new token (classic)" 클릭
2. 토큰 이름: Zellyy Finance Linear Integration
3. 만료 기간: 90 days (또는 원하는 기간)
4. 필수 권한 선택:
   • repo: 전체 리포지토리 액세스
   • workflow: GitHub Actions 워크플로우 관리
   • admin:repo_hook: 웹훅 관리

2.3 토큰 복사

• 생성된 토큰을 안전한 곳에 저장
• 형식: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3단계: 자동 설정 실행

3.1 설정 스크립트 실행

# Linear API 키와 함께 전체 설정 실행
npm run linear:setup -- --setup --linear-api=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 또는 직접 실행
node scripts/linear-github-setup.cjs --setup --linear-api=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3.2 설정 결과 확인

스크립트 실행 후 다음 파일들이 생성/업데이트됩니다:

• .env.linear: 환경 변수 설정 파일
• 콘솔에 출력되는 설정 안내 확인

3.3 환경 변수 설정

생성된 .env.linear 파일의 내용을 기존 .env 파일에 추가하거나 새로 생성:

# .env.linear 내용을 .env로 복사
cat .env.linear >> .env

# 또는 .env.linear를 .env로 복사
cp .env.linear .env

4단계: GitHub Secrets 설정

4.1 리포지토리 Secrets 페이지 접근

1. GitHub 리포지토리 페이지 이동
2. Settings → Secrets and variables → Actions 클릭

4.2 필수 Secrets 추가

"New repository secret" 클릭하여 다음 secrets 추가:

필수 Secret

• Name: LINEAR_API_KEY
• Value: lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (1단계에서 생성한 키)

선택적 Secrets (향후 확장용)

• Name: SLACK_BOT_TOKEN

• Value: xoxb-your-slack-bot-token (Slack 연동용)

• Name: SLACK_WEBHOOK_URL

• Value: https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK (Slack 알림용)

4.3 Secrets 확인

Settings → Secrets에서 LINEAR_API_KEY가 추가되었는지 확인합니다.

5단계: Linear 웹훅 설정

5.1 Linear 웹훅 페이지 접근

1. Linear 워크스페이스에서 Settings → API → Webhooks 이동
2. "Create webhook" 클릭

5.2 웹훅 구성

기본 설정

• Label: GitHub Integration - Zellyy Finance
• URL: https://api.github.com/repos/zellycloud/zellyy-finance/dispatches

Resource Types 선택

다음 이벤트 타입들을 선택:

• ✅ Issue (이슈 생성, 업데이트, 상태 변경)
• ✅ Comment (코멘트 생성, 업데이트)
• ✅ IssueLabel (레이블 변경)

팀 선택

• Team: Zellyy 선택 (또는 모든 팀)

5.3 웹훅 활성화

• Enabled 체크박스 확인
• "Create webhook" 클릭

6단계: 연동 테스트

6.1 테스트 브랜치 생성

# 새 브랜치 생성
git checkout -b feature/test-linear-integration

# 테스트 파일 생성
echo "# Linear Integration Test" > test-linear.md
git add test-linear.md

6.2 Linear 이슈 ID가 포함된 커밋

# Linear 이슈 ID를 포함한 커밋 메시지
git commit -m "feat: test Linear integration [ZEL-1]"

# 브랜치 푸시
git push origin feature/test-linear-integration

6.3 Pull Request 생성

1. GitHub에서 Pull Request 생성
2. 제목: Test Linear integration (ZEL-1)
3. 설명에 다음 내용 포함:

   ## Linear 이슈
   Closes ZEL-1
   
   ## 변경 내용
   Linear GitHub 연동 테스트를 위한 Pull Request입니다.
   

6.4 연동 동작 확인

GitHub Actions 확인

1. Actions 탭에서 워크플로우 실행 확인
2. Linear Integration 워크플로우가 성공적으로 실행되는지 확인
3. 로그에서 Linear API 호출 결과 확인

Linear 이슈 확인

1. Linear에서 ZEL-1 이슈 확인
2. 자동으로 추가된 코멘트 확인:

   🔗 Pull Request 생성
   
   URL: https://github.com/zellycloud/zellyy-finance/pull/XXX
   작성자: @username
   

6.5 전체 플로우 테스트

# 통합 테스트 실행
npm run linear:test -- --api-key=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 설정 검증
npm run linear:setup -- --verify --linear-api=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

설정 완료 확인

✅ 체크리스트

• Linear API 키 생성 및 설정
• GitHub 개인 액세스 토큰 생성 (선택사항)
• 자동 설정 스크립트 실행 성공
• GitHub Secrets에 LINEAR_API_KEY 추가
• Linear 웹훅 설정 완료
• 테스트 Pull Request 생성
• GitHub Actions 워크플로우 실행 성공
• Linear 이슈에 자동 코멘트 생성 확인
• 통합 테스트 모두 통과

🎉 성공 시 기대 결과

1. Pull Request 생성 시: Linear 이슈에 PR 링크 코멘트 자동 추가
2. Pull Request 병합 시: Linear 이슈 상태 자동 변경 (Done)
3. 코드 리뷰 시: Linear 이슈에 리뷰 상태 코멘트 추가
4. 릴리즈 시: Linear 이슈들을 포함한 릴리즈 노트 자동 생성

문제 해결

자주 발생하는 문제들

1. Linear API 연결 실패

증상: Linear API Error: Unauthorized

해결 방법:

# API 키 확인
npm run linear:test -- --api-key=your-api-key

# 권한 확인
# Linear Settings → API → Personal API keys에서 키 권한 재확인

2. GitHub Actions 실행 실패

증상: Workflow에서 LINEAR_API_KEY 오류

해결 방법:

1. GitHub 리포지토리 Settings → Secrets 확인
2. LINEAR_API_KEY Secret이 올바르게 설정되었는지 확인
3. Secret 값에 공백이나 특수문자가 없는지 확인

3. 웹훅 이벤트 수신 실패

증상: Linear 이벤트가 GitHub으로 전달되지 않음

해결 방법:

1. Linear Webhooks 설정에서 URL 확인:

   https://api.github.com/repos/zellycloud/zellyy-finance/dispatches
   

2. Resource Types가 올바르게 선택되었는지 확인
3. 웹훅이 활성화(Enabled)되어 있는지 확인

4. 이슈 ID 추출 실패

증상: PR이나 커밋에서 Linear 이슈 ID를 찾지 못함

해결 방법:

• 올바른 형식 사용:

  # 커밋 메시지
  git commit -m "feat: new feature [ZEL-123]"
  git commit -m "fix: bug fix (Fixes ZEL-456)"
  
  # PR 제목
  "Add new feature (ZEL-123)"
  "Fix critical bug [ZEL-456]"
  
  # PR 설명
  Closes ZEL-123
  Related to ZEL-456
  

로그 확인 방법

GitHub Actions 로그

1. GitHub 리포지토리 → Actions 탭
2. 해당 워크플로우 실행 클릭
3. 각 단계별 로그 확인

Linear API 응답 확인

# 디버그 모드로 테스트 실행
DEBUG=true npm run linear:test -- --api-key=your-api-key

추가 도움이 필요한 경우

1. Linear 지원: Linear Support
2. GitHub Actions 문서: GitHub Actions Documentation
3. 프로젝트 이슈: GitHub 이슈로 문의

---

다음 단계

Linear GitHub 기본 연동이 완료되면 다음 고급 기능들을 설정할 수 있습니다:

• Slack 연동: 팀 협업 알림 자동화
• 릴리즈 자동화: semantic-release와 완전 연동
• 프로젝트 대시보드: 자동화된 리포팅 시스템

각 기능별 상세 가이드는 별도 문서에서 제공됩니다.