GitHub Actions Workflows
PlayStat 프로젝트의 GitHub Actions 워크플로우 설명입니다.
📋 워크플로우 목록
1. Data Collection Cron Jobs (data-collection.yml)
목적: 스포츠 데이터 자동 수집 및 분석
스케줄:
- ⚽ Football: 매일 01:00 UTC (KST 10:00)
- 🏀 Basketball: 매일 02:00 UTC (KST 11:00)
- ⚾ Baseball: 매일 03:00 UTC (KST 12:00)
수동 실행:
# GitHub UI에서 Actions > Data Collection Cron Jobs > Run workflow
# 또는 gh CLI 사용:
gh workflow run data-collection.yml -f sport=all
gh workflow run data-collection.yml -f sport=football
gh workflow run data-collection.yml -f sport=basketball
gh workflow run data-collection.yml -f sport=baseball
필요한 Secrets:
SITE_URL: 배포된 사이트 URL (예: https://playstat.space)CRON_SECRET: 크론 API 인증 토큰
동작 방식:
각 스포츠별로 5개의 순차적인 작업을 15초 간격으로 실행합니다:
-
Collect Matches: 경기 일정 및 결과 수집
- 엔드포인트:
/api/cron/collect-{sport}
- Football: EPL, La Liga, Serie A, Bundesliga, Ligue 1
- Basketball: NBA
- Baseball: MLB
-
Collect Team Data: 팀 시즌 스탯 및 순위표 수집
- 엔드포인트:
/api/cron/collect-team-data?sport={sport}
- 7일 이내 예정된 경기의 팀 데이터만 수집
-
Generate Analysis: AI 기반 경기 분석 생성
- 엔드포인트:
/api/cron/generate-analysis?sport={sport}
- 48시간 이내 경기에 대한 GPT-4o 분석
-
Generate Daily Report: 데일리 리포트 생성
- 엔드포인트:
/api/cron/generate-daily-report?sport={sport}
- 오늘/내일 경기 종합 리포트
-
Update Live Matches: 실시간 스코어 업데이트
- 엔드포인트:
/api/cron/update-live-matches?sport={sport}
- 진행 중이거나 당일 경기의 점수 및 상태 업데이트
2. Manual Data Collection Trigger (manual-trigger.yml)
목적: 수동으로 데이터 수집 트리거
기능:
- 원하는 스포츠 선택 (football/basketball/baseball/all)
- Chain 옵션 설정 (후속 작업 실행 여부)
- All 선택 시 모든 스포츠 순차 실행 (Rate limiting 고려하여 15초 간격)
사용법:
# GitHub UI에서 Actions > Manual Data Collection Trigger > Run workflow
# 스포츠 선택 + Chain 옵션 선택
특징:
- 실행 결과를 JSON으로 출력
- HTTP 상태 코드 확인
- 각 요청 사이 15초 대기 (BallDontLie API Rate Limiting 준수)
3. API Health Check (health-check.yml)
목적: API 및 사이트 상태 모니터링
스케줄: 매시간 실행
체크 항목:
- ✅ PlayStat 사이트 Health Check
- ✅ BallDontLie Football API 상태
- ✅ BallDontLie Basketball API 상태
- ✅ BallDontLie Baseball API 상태
수동 실행:
gh workflow run health-check.yml
🔐 Required Secrets 설정
GitHub 저장소 Settings > Secrets and variables > Actions에서 설정:
| Secret Name | Description | Example |
|---|
SITE_URL | 배포된 사이트 URL | https://playstat.space |
CRON_SECRET | 크론 API 인증 토큰 | .env 파일의 CRON_SECRET 값 |
🚨 중요 사항
Rate Limiting
BallDontLie Free Tier는 분당 5회 요청 제한이 있습니다:
- 각 크론 작업이 1시간 간격으로 실행되도록 스케줄됨
- Manual Trigger에서 "all" 선택 시 15초 간격으로 실행
- 크론 내부에서도 13초 딜레이 적용
GitHub Actions Only
모든 크론 작업은 GitHub Actions에서 실행됩니다:
- ⚽ Football: EPL, La Liga, Serie A, Bundesliga, Ligue 1
- 🏀 Basketball: NBA
- ⚾ Baseball: MLB
- Health Check (별도 워크플로우)
Vercel Cron: 사용하지 않음 (vercel.json의 crons 배열은 비어있음)
📊 모니터링
워크플로우 실행 확인
# 최근 워크플로우 실행 확인
gh run list --workflow=data-collection.yml
# 특정 실행 로그 보기
gh run view <run-id>
실패 시 대응
- GitHub Actions 탭에서 실패한 워크플로우 확인
- 로그에서 에러 메시지 확인
- API Rate Limit 초과 시 → 다음 시간까지 대기
- 인증 실패 시 → Secrets 확인
🔧 트러블슈팅
401 Unauthorized
CRON_SECRET이 올바르게 설정되었는지 확인- Vercel 환경 변수와 동일한 값인지 확인
429 Rate Limit Exceeded
- BallDontLie API 제한 초과
- 13분 후 재시도
Workflow Not Triggering
- 저장소가 Public인지 확인 (Private는 별도 설정 필요)
- cron 표현식 검증
- GitHub Actions 활성화 확인
📝 워크플로우 수정
워크플로우 파일 수정 후:
git add .github/workflows/
git commit -m "Update workflow"
git push
변경사항은 즉시 반영되며, 다음 스케줄 시간 또는 수동 실행 시 적용됩니다.
Built for PlayStat Multi-Sport Analytics Platform
