참고:
last-sync.json상태 파일은 첫 번째 성공적인 동기화 시 자동 생성됩니다. 첫 실행 시 '파일 없음' 경고는 무시하세요.
포트폴리오 자동 동기화
GitHub 리포지토리를 포트폴리오 웹사이트에 자동으로 동기화합니다.
워크플로우
1단계: 설정 수집
사용자에게 다음을 질문합니다:
- GitHub 사용자 이름: (git config 기본값)
- 포트폴리오 유형:
static(projects-data.js) 또는supabase(API) - 포트폴리오 디렉토리: 포트폴리오 프로젝트 경로
- 필터: 제외할 리포지토리 (보관됨, 포크, 특정 이름)
2단계: GitHub API를 통해 리포지토리 가져오기
GET /users/{username}/repos?per_page=100&sort=updated&direction=desc
추출: name, description, html_url, homepage, language, topics, updated_at
필터링:
- 포크 (사용자가 허용하지 않은 경우)
- 프로필 리포지토리 (
{username}/{username}) - 보관된 리포지토리
3단계: 변경 감지
last-sync.json (스킬 디렉토리에 저장)과 비교합니다.
- 새 리포지토리: 마지막 동기화에 없음 → 전체 처리
- 업데이트된 리포지토리:
updated_at변경됨 → 다시 스크린샷 - 변경 없는 리포지토리: 건너뛰기
4단계: 스크린샷 캡처
homepage 또는 배포 URL이 있는 리포지토리:
const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.URL, { waitUntil: 'networkidle', timeout: 15000 });
await page.screenshot({ path: `/tmp/portfolio-${name}.png`, fullPage: false });
await browser.close();
포트폴리오의 스크린샷 디렉토리에 저장합니다.
5단계: 포트폴리오 데이터 업데이트
정적 (projects-data.js)
{
title: '{repo.name}',
description: 'Auto-generated: {description}',
tech: '{language},{topics}',
github_url: '{html_url}',
live_url: '{homepage || ""}',
featured: false
}
Supabase
const res = await fetch('https://your-site.com/api/projects', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' },
body: JSON.stringify(projectData)
});
6단계: 동기화 상태 저장
{
"lastSync": "2026-05-12T18:30:00Z",
"repos": {
"example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
}
}
7단계: 결과 보고
동기화 완료:
+ 2개 신규 (Cyberian, Image Enhancer)
+ 1개 스크린샷 캡처
+ 1개 업데이트 (Portfolio)
- 0개 오류
참고 사항
- 스크린샷은 Playwright와 유효한 URL이 필요합니다. 홈페이지가 없으면 건너뜁니다.
- 기존 프로젝트의
featured: true는 변경하지 마세요. 사용자만 승격할 수 있습니다. - 주간 동기화를 위해 cron/GitHub Actions로 예약하세요.
오류 처리
| 원인 | 해결 방법 |
|---|---|
| GitHub API가 401 Unauthorized 반환 | 토큰이 없거나 만료됨. GITHUB_TOKEN 환경 변수를 설정하세요. github.com/settings/tokens에서 public_repo 범위의 새 Personal Access Token을 생성하세요. |
| GitHub API 속도 제한 초과 (403) | 인증되지 않은 요청은 시간당 60회로 제한됩니다. 인증된 요청: 시간당 5000회. 토큰을 추가하세요. 이미 인증된 경우 재설정을 기다리세요 (X-RateLimit-Reset 헤더 확인). |
리포지토리에 homepage 필드와 배포 URL이 모두 없음 | 스크린샷을 캡처할 수 없습니다. 출력에서 "라이브 미리보기 없음"으로 표시하세요. GitHub URL을 대체 링크로 사용하세요. |
| Playwright 브라우저 시작 실패 | Chromium이 설치되지 않음. npx playwright install chromium을 실행하세요. 헤드리스 서버에서는 --no-sandbox 플래그를 추가하세요: chromium.launch({ headless: true, args: ['--no-sandbox'] }). |
| 스크린샷 URL이 15초 후 404 또는 타임아웃 반환 | 배포 URL이 오래되었거나 사이트가 다운됨. 이 리포지토리의 스크린샷은 건너뜁니다. URL과 오류를 수동 검토를 위해 failed-screenshots.json 파일에 기록하세요. |
projects-data.js에 자동 생성이 깨뜨릴 사용자 정의 포맷팅이 있음 | 정규식 기반 삽입이 수동 코드를 손상시킬 수 있습니다. 먼저 파일을 읽어 비표준 구조를 감지하세요. 감지되면 새 항목이 포함된 주석 블록을 추가하고 사용자에게 수동 병합을 요청하세요. |
| Supabase API 삽입이 외래 키 또는 스키마 제약 조건으로 실패 | 포트폴리오 스키마가 자동 생성된 페이로드 모양과 다를 수 있습니다. 먼저 Supabase 테이블 스키마를 읽으세요. 필드를 명시적으로 매핑하세요 (확산 연산자 사용하지 않음). 커밋 전에 200을 반환하는 dry-run POST로 유효성을 검증하세요. |
last-sync.json이 손상되었거나 수동으로 편집됨 | try-catch에서 JSON으로 파싱하세요. 실패 시 last-sync.json.bak으로 이름을 바꾸고 처음부터 새로 동기화를 시작하세요. 증분 감지가 손실되었음을 사용자에게 경고하세요. |
GitHub API 패턴
리포지토리 검색
import requests, os
headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}
# 모든 리포지토리 가져오기 (페이지네이션)
repos = []
page = 1
while True:
r = requests.get(f"https://api.github.com/user/repos?per_page=100&page={page}&sort=updated", headers=headers)
batch = r.json()
if not batch: break
repos.extend(batch)
page += 1
# 필터: 포크가 아니고, 보관되지 않았으며, 설명이 있는 리포지토리만
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]
속도 제한
- GitHub API: 시간당 5000개 요청 (인증됨).
X-RateLimit-Remaining헤더를 확인하세요. - 500개 이상의 리포지토리가 있는 경우 조건부 요청 (
If-None-Match와 ETag) 사용 - 스크린샷 캡처 사이에 1초 대기 (GitHub 자산 속도 제한 방지)
Playwright 스크린샷 패턴
from playwright.sync_api import sync_playwright
def capture(url, output_path):
with sync_playwright() as p:
browser = p.chromium.launch()
page = browser.new_page(viewport={"width": 1280, "height": 800})
page.goto(url, timeout=15000, wait_until="networkidle")
page.screenshot(path=output_path, full_page=False)
browser.close()
오류 복구
- 페이지 로드 타임아웃 -> 한 번 재시도, 여전히 실패하면 건너뛰기 (출력에 표시)
- 비공개 리포지토리 -> 건너뛰기 (인증 없이 스크린샷 불가)
- 페이지 충돌 -> 오류 상태를 스크린샷으로 캡처
- DNS 실패 -> 로그 메시지와 함께 건너뛰기
캐싱 전략
import hashlib, json, os
cache_file = ".sync-cache.json"
cache = json.load(open(cache_file)) if os.path.exists(cache_file) else {}
for repo in repos:
key = hashlib.md5(f"{repo['full_name']}:{repo['pushed_at']}".encode()).hexdigest()
if cache.get(repo['full_name']) == key:
continue # 건너뛰기: 마지막 동기화 이후 변경 없음
# ... 스크린샷 캡처, 항목 업데이트 ...
cache[repo['full_name']] = key
json.dump(cache, open(cache_file, 'w'))
체크리스트
- 리포지토리를 가져오기 전에 GitHub 토큰에 올바른 범위(repo, read:user)가 있는지 확인
- 유효한 홈페이지 URL(HEAD 확인 먼저)이 있는 리포지토리에 대해서만 스크린샷 실행
- 고아 프로세스를 방지하기 위해 finally 블록에서 Playwright 브라우저 종료
- 새 항목을 upsert하기 전에 기존 포트폴리오 사용자 정의 유지
- 변경 사항을 미리 보기 위해 dry-run 모드 사용 가능
출처
- GitHub REST API v3 문서 (docs.github.com/en/rest/repos/repos) — 리포지토리 목록, 필터링 및 페이지네이션
- Playwright 문서 (playwright.dev/docs/api/class-playwright) — 헤드리스 브라우저 실행, 스크린샷 및 뷰포트 구성
- Supabase JavaScript 클라이언트 문서 (supabase.com/docs/reference/javascript) — API 삽입, upsert 및 인증 패턴
- Node.js
fs모듈 문서 (nodejs.org/api/fs.html) — 동기화 상태 안전을 위한 원자적 이름 변경을 포함한 파일 읽기/쓰기 - Personal Access Token 모범 사례 (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — 범위, 만료 및 안전한 저장
- GitHub Actions cron 스케줄링 (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — 주간 동기화 자동화 패턴
- Al Sweigart 저 "Automate the Boring Stuff with Python" (No Starch Press, 2판, 2019) — JavaScript 자동화 작업에 적용 가능한 자동화 안정성 패턴
안티패턴
| 패턴 | 문제 | 해결 방법 |
|---|---|---|
| 기존 사용자 정의 확인 없이 동기화 | 자동 생성된 항목이 사용자가 설정한 수작업 프로젝트 설명, featured 플래그 또는 사용자 정의 순서를 덮어쓸 수 있습니다. | 대상 파일을 먼저 읽으세요. 비표준 구조를 감지하세요. featured: true 항목의 경우 모든 필드를 유지하세요. 새롭거나 변경된 리포지토리만 upsert하세요. |
| 모든 리포지토리에 대해 무차별적으로 스크린샷 캡처 | 라이브 데모가 없는 리포지토리는 Playwright 실행 시간(각 약 3초)을 낭비합니다. URL이 깨진 리포지토리는 쓸모없는 오류 스크린샷을 생성합니다. | 사전 필터링: homepage 필드가 비어 있지 않고 HEAD 요청에 200을 반환하는 리포지토리만 스크린샷을 캡처합니다. |
| 제한된 또는 느린 연결에서 동기화 실행 | 수십 개의 리포지토리를 클론하거나 스크린샷을 캡처하면 상당한 대역폭과 시간이 소모될 수 있습니다. | 10개씩 배치로 실행하세요. 변경 사항을 실행하지 않고 나열하는 --dry-run 플래그를 추가하세요. |
| 쓰기에 Supabase anon 키 대신 service_role 키 사용 | anon 키는 upsert를 차단하는 행 수준 보안 제한이 있습니다. | service_role 키를 주의해서 사용하세요. 환경 변수에 저장하고 코드에 절대 저장하지 마세요. 동기화 함수에 대한 테이블 수준 RLS 정책을 추가하세요. |
| 동기화 후 Playwright 브라우저 프로세스 정리하지 않음 | 각 chromium.launch()는 프로세스를 생성합니다. 고아 프로세스는 메모리를 축적하고 시스템 리소스를 고갈시킬 수 있습니다. | finally 블록에서 항상 browser.close()를 호출하세요. 실행된 브라우저를 배열에 추적하고 SIGINT/SIGTERM에서 강제 종료하세요. |
| 포트폴리오 데이터 경로를 구성에서 읽지 않고 하드코딩 | 경로는 프로젝트 간에 변경됩니다. 하드코딩된 경로는 다른 머신에서 처음 사용 시 깨집니다. | 1단계에서 포트폴리오 디렉토리를 질문하세요. 해당 기본 경로에서 projects-data.js 경로를 파생하세요. 재사용을 위해 동기화 상태에 저장하세요. |