검색 K
밝은/어두운 배경
GitHub Actions 워크플로우
게시물 정보
- 작성일: 2026년 6월 8일 월요일 (약 1개월 전)
- 글쓴이: claude.ai
- 주제어: #기술 문서 #운영 매뉴얼 #claude.ai #GitHub Actions 워크플로우
rss-scraper.yml — RSS 수집 · 커밋 · Vercel 배포
트리거
| 방식 | 시각 (KST) | cron (UTC) |
|---|---|---|
| 스케줄 — 오전 | 09:30 | 30 0 * * * |
| 스케줄 — 오후 | 13:30 | 30 4 * * * |
| 스케줄 — 새벽 | 익일 05:30 | 00 21 * * * |
| 수동 | — | workflow_dispatch |
| API 트리거 | 운영자 승인·철회 확인 즉시 | _github.ts triggerScraper() |
triggerScraper()는 호출 전 status=in_progress 워크플로우가 있으면 트리거를 스킵해 중복 실행을 방지합니다.
스케줄 변경
.github/workflows/rss-scraper.yml의 cron 항목을 수정합니다. cron 값은 UTC 기준입니다.
KST ↔ UTC 변환: KST에서 9시간을 빼면 UTC가 됩니다.
예) KST 18:00 → UTC 09:00 → 0 9 * * *
실행 단계
1. Checkout main (fetch-depth: 0, GH_TOKEN 사용)
↓
2. pnpm 환경 설정 + 의존성 설치 (pnpm store 캐시 활용)
↓
3. pnpm rss:env scrape → scraper/index.ts 실행
· JSON / Markdown 파일 생성·수정
· new_posts_count.txt 에 신규 포스트 수 기록
↓
4. Commit & push
· docs/src/_data/ (JSON 스토어)
· docs/src/ (Markdown 파일)
· git add -u docs/src/ (철회된 피드의 삭제 파일도 포함)
· 변경사항이 없으면 커밋 스킵
· 커밋 메시지: "[build] 정기 업데이트 (새 글: N건)"
↓
5. Vercel 자동 배포 트리거
· vercel-build-check.sh 가 커밋 메시지에 "[build]" 포함 여부 확인
· 포함 → exit 1 → Vercel 빌드 진행
· 미포함 → exit 0 → Vercel 빌드 스킵빌드 조건 분기: VitePress 빌드와 Vercel 배포는 GitHub Actions에서 직접 실행하지 않습니다. 워크플로우는 파일을 커밋·푸시하는 역할만 하며, Vercel의 Git 연동이 푸시를 감지해
vercel-build-check.sh를 실행합니다. 신규 포스트가 없어 커밋이 발생하지 않으면 Vercel도 트리거되지 않습니다.
new_posts_count.txt
스크래퍼 실행 후 신규 포스트 수가 기록되는 파일입니다. 저장소에 0이 커밋된 상태로 유지됩니다. 워크플로우에서 cat new_posts_count.txt로 값을 읽어 커밋 메시지에 포함합니다.
bash
NEW_COUNT=$(cat new_posts_count.txt 2>/dev/null || echo "0")
git commit -m "[build] 정기 업데이트 (새 글: ${NEW_COUNT}건)"수동 실행
GitHub 저장소 → Actions 탭 → Scheduled RSS Scraper 워크플로우 → "Run workflow" 버튼.
피드를 신규 등록한 직후 즉시 수집하고 싶을 때 사용합니다.
필요한 Secrets
| Secret | 설명 |
|---|---|
GH_TOKEN | checkout · push 권한이 있는 PAT. contents: write 권한 필요 |
DATABASE_URL | Neon DB 연결 문자열 |
send-reminders.yml — 미처리 신청 재알림
트리거
| 방식 | 시각 (KST) | cron (UTC) |
|---|---|---|
| 스케줄 | 매일 10:00 | 0 1 * * * |
| 수동 | — | workflow_dispatch |
실행 단계
1. Checkout + pnpm 환경 설정 + 의존성 설치
↓
2. pnpm reminder → scripts/send-reminders.ts 실행
· DB에서 재알림 대상 조회 (3일 이상 미처리, 5회 미만)
· 운영자에게 재알림 이메일 발송
· 발송 성공 건만 reminder_count · last_reminded_at 갱신
↓
3. 실패 건이 1건 이상이면 exit 1 → Actions 실패로 표시필요한 Secrets
| Secret | 설명 |
|---|---|
DATABASE_URL | Neon DB 연결 문자열 |
RESEND_API_KEY | Resend API 키 |
ADMIN_EMAIL | 운영자 수신 이메일 |
REVIEW_BASE_URL | 이메일 내 링크 기준 URL |
Vercel 배포 연동 (vercel-build-check.sh)
Vercel 프로젝트의 Ignored Build Step 설정에 이 스크립트를 등록합니다.
bash vercel-build-check.shVercel은 푸시를 감지할 때마다 이 스크립트를 실행합니다.
| 커밋 메시지 | 스크립트 종료 코드 | Vercel 동작 |
|---|---|---|
[build] 포함 | exit 1 | 빌드 진행 |
[build] 미포함 | exit 0 | 빌드 스킵 |
[build]는 rss-scraper.yml의 커밋 메시지에만 포함됩니다. 코드 수정 등 다른 커밋은 Vercel 빌드를 트리거하지 않습니다. 코드 변경 후 즉시 배포가 필요하면 커밋 메시지에 [build]를 수동으로 포함시킵니다.
GitHub Secrets 전체 목록
저장소 Settings → Secrets and variables → Actions에서 관리합니다.
| Secret | 사용 워크플로우 | 설명 |
|---|---|---|
GH_TOKEN | rss-scraper.yml | checkout · push용 PAT (contents: write) |
DATABASE_URL | 양쪽 모두 | Neon DB 연결 문자열 |
RESEND_API_KEY | send-reminders.yml | Resend API 키 |
ADMIN_EMAIL | send-reminders.yml | 운영자 수신 이메일 |
REVIEW_BASE_URL | send-reminders.yml | 이메일 내 링크 기준 URL |
GH_REPO | API (_github.ts) | 즉시 트리거용 저장소 경로 (owner/repo) |
GH_REPO·GH_TOKEN은_github.ts의triggerScraper()에서도 사용합니다. Secrets에 설정되지 않으면 트리거를 스킵하고 경고 로그만 출력합니다.
워크플로우 실패 대응
스크래퍼 실패
Actions 탭 → 실패한 실행 → 로그 확인.
| 로그 패턴 | 원인 | 대응 |
|---|---|---|
크리티컬 런타임 에러 | 비정상 종료 (락 해제 안 됨) | 스택 트레이스 확인 · 락 강제 해제 |
[FEED N/M] ... FAILED | 특정 피드 fetch 실패 | 해당 피드 URL 상태 확인 |
| DB 연결 오류 | DATABASE_URL 미설정 또는 Neon 장애 | Secret 확인 · Neon 대시보드 확인 |
| push 권한 오류 | GH_TOKEN 만료 또는 권한 부족 | PAT 재발급 후 Secret 갱신 |
재알림 스크립트 실패
로그에서 발송 실패 또는 UPDATE 실패 행을 확인합니다. Resend API 한도 초과나 일시적 네트워크 문제가 원인인 경우가 많으며, 다음 스케줄 실행에서 자동으로 재시도됩니다.
Vercel 배포가 트리거되지 않는 경우
- 해당 커밋 메시지에
[build]가 포함되어 있는지 확인합니다. - Vercel 프로젝트의 Ignored Build Step에
bash vercel-build-check.sh가 설정되어 있는지 확인합니다. - Vercel 대시보드 → Deployments에서 스킵된 배포(
SKIPPED) 로그를 확인합니다.