8343b25439
✨ 주요 개선사항: - any 타입 83개에서 62개로 21개 수정 (25% 감소) - 모든 ESLint 에러 11개 → 0개 완전 해결 - 타입 안전성 대폭 향상으로 런타임 오류 가능성 감소 🔧 수정된 파일들: • PWADebug.tsx - 사용하지 않는 import들에 _ prefix 추가 • categoryUtils.ts - 불필요한 any 캐스트 제거 • TransactionsHeader.tsx - BudgetData 인터페이스 정의 • storageUtils.ts - generic 타입과 unknown 타입 적용 • 각종 error handler들 - Error | {message?: string} 타입 적용 • test 파일들 - 적절한 mock 인터페이스 정의 • 유틸리티 파일들 - any → unknown 또는 적절한 타입으로 교체 🏆 성과: - 코드 품질 크게 향상 (280 → 80 문제로 71% 감소) - TypeScript 컴파일러의 타입 체크 효과성 증대 - 개발자 경험 개선 (IDE 자동완성, 타입 추론 등) 🧹 추가 정리: - ESLint no-console/no-alert 경고 해결 - Prettier 포맷팅 적용으로 코드 스타일 통일 🎯 다음 단계: 남은 62개 any 타입 계속 개선 예정 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
344 lines
9.5 KiB
Markdown
344 lines
9.5 KiB
Markdown
# Linear GitHub 연동 가이드
|
|
|
|
Linear와 GitHub 간의 기본 연결 설정 및 구성 가이드입니다.
|
|
|
|
## 📋 목차
|
|
|
|
- [개요](#개요)
|
|
- [사전 요구사항](#사전-요구사항)
|
|
- [1단계: Linear API 키 생성](#1단계-linear-api-키-생성)
|
|
- [2단계: GitHub 개인 액세스 토큰 생성](#2단계-github-개인-액세스-토큰-생성)
|
|
- [3단계: 자동 설정 실행](#3단계-자동-설정-실행)
|
|
- [4단계: GitHub Secrets 설정](#4단계-github-secrets-설정)
|
|
- [5단계: Linear 웹훅 설정](#5단계-linear-웹훅-설정)
|
|
- [6단계: 연동 테스트](#6단계-연동-테스트)
|
|
- [문제 해결](#문제-해결)
|
|
|
|
## 개요
|
|
|
|
이 가이드는 Linear 프로젝트 관리 도구와 GitHub 리포지토리 간의 양방향 연동을 설정하는 방법을 설명합니다.
|
|
|
|
### 연동 기능
|
|
|
|
- **이슈 상태 동기화**: PR 상태에 따른 Linear 이슈 상태 자동 업데이트
|
|
- **자동 코멘트**: GitHub 이벤트를 Linear 이슈에 자동으로 코멘트
|
|
- **릴리즈 관리**: semantic-release와 연동된 자동 릴리즈 노트 생성
|
|
- **워크플로우 자동화**: GitHub Actions를 통한 완전 자동화
|
|
|
|
## 사전 요구사항
|
|
|
|
### 계정 및 권한
|
|
|
|
- **Linear 계정**: 워크스페이스 관리자 권한
|
|
- **GitHub 계정**: 리포지토리 관리자 권한
|
|
- **Node.js**: 18.0.0 이상
|
|
|
|
### 필수 파일 확인
|
|
|
|
다음 파일들이 프로젝트에 존재하는지 확인하세요:
|
|
|
|
```bash
|
|
# 자동 확인
|
|
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 설정 스크립트 실행
|
|
|
|
```bash
|
|
# 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` 파일에 추가하거나 새로 생성:
|
|
|
|
```bash
|
|
# .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 테스트 브랜치 생성
|
|
|
|
```bash
|
|
# 새 브랜치 생성
|
|
git checkout -b feature/test-linear-integration
|
|
|
|
# 테스트 파일 생성
|
|
echo "# Linear Integration Test" > test-linear.md
|
|
git add test-linear.md
|
|
```
|
|
|
|
### 6.2 Linear 이슈 ID가 포함된 커밋
|
|
|
|
```bash
|
|
# 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. **설명**에 다음 내용 포함:
|
|
```markdown
|
|
## 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 전체 플로우 테스트
|
|
|
|
```bash
|
|
# 통합 테스트 실행
|
|
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`
|
|
|
|
**해결 방법**:
|
|
```bash
|
|
# 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를 찾지 못함
|
|
|
|
**해결 방법**:
|
|
- 올바른 형식 사용:
|
|
```bash
|
|
# 커밋 메시지
|
|
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 응답 확인
|
|
```bash
|
|
# 디버그 모드로 테스트 실행
|
|
DEBUG=true npm run linear:test -- --api-key=your-api-key
|
|
```
|
|
|
|
### 추가 도움이 필요한 경우
|
|
|
|
1. **Linear 지원**: [Linear Support](https://linear.app/contact)
|
|
2. **GitHub Actions 문서**: [GitHub Actions Documentation](https://docs.github.com/en/actions)
|
|
3. **프로젝트 이슈**: GitHub 이슈로 문의
|
|
|
|
---
|
|
|
|
## 다음 단계
|
|
|
|
Linear GitHub 기본 연동이 완료되면 다음 고급 기능들을 설정할 수 있습니다:
|
|
|
|
- **Slack 연동**: 팀 협업 알림 자동화
|
|
- **릴리즈 자동화**: semantic-release와 완전 연동
|
|
- **프로젝트 대시보드**: 자동화된 리포팅 시스템
|
|
|
|
각 기능별 상세 가이드는 별도 문서에서 제공됩니다. |