# 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와 완전 연동
- **프로젝트 대시보드**: 자동화된 리포팅 시스템

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