注:
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: '自動生成: {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が必要です。homepageがない場合はスキップします。
- 既存プロジェクトの
featured: trueは絶対に変更しないでください。プロモートはユーザーのみが行えます。 - cron / GitHub Actionsを使用して週次同期をスケジュールできます。
エラーハンドリング
| 原因 | 修正方法 |
|---|---|
| GitHub APIが401 Unauthorizedを返す | トークンがないか期限切れ。GITHUB_TOKEN 環境変数を設定してください。github.com/settings/tokens でスコープ public_repo の新しいパーソナルアクセストークンを生成します。 |
| 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が404または15秒のタイムアウト | デプロイURLが古いかサイトがダウンしています。このリポジトリのスクリーンショットをスキップします。URLとエラーを failed-screenshots.json ファイルに記録し、手動確認を促します。 |
projects-data.js のカスタム書式が自動生成により壊れる可能性がある | 正規表現ベースの挿入で手書きコードが破損する可能性があります。まずファイルを読み込み、非標準構造を検出します。検出された場合は、新しいエントリを含むコメントブロックを追加し、ユーザーに手動マージを依頼します。 |
| Supabase API insertが外部キーまたはスキーマ制約で失敗する | ポートフォリオスキーマが自動生成ペイロードの形状と異なる可能性があります。まずSupabaseテーブルスキーマを読み取ります。フィールドを明示的にマッピングします(スプレッド演算子は使用しない)。コミットする前に、200を返すドライラン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: 5,000リクエスト/時間(認証済み)。
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()
エラーリカバリ
- ページロードのタイムアウト -> 1回リトライ、それでも失敗した場合はスキップ(出力にマーク)
- プライベートリポジトリ -> スキップ(認証なしではスクリーンショット不可)
- ページクラッシュ -> エラー状態をスクリーンショットとしてキャプチャ
- 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)があることをリポジトリ取得前に確認
- スクリーンショットは有効なhomepage URLを持つリポジトリに対してのみ実行(最初にHEADチェック)
- Playwrightブラウザはfinallyブロックで閉じ、ゾンビプロセスを防止
- 既存のポートフォリオカスタマイズを新しいエントリのアップサート前に保持
- ドライランモードで変更をプレビュー可能(実行せずに)
参照ソース
- 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 insert、upsert、認証パターン
- Node.js
fsモジュール ドキュメント (nodejs.org/api/fs.html) — 同期状態の安全なファイル読み書き(アトミックリネーム) - パーソナルアクセストークンのベストプラクティス (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) — 週次同期自動化パターン
- 「退屈なことはPythonにやらせよう」Al Sweigart 著(No Starch Press、第2版、2019年) — JavaScript自動化タスクに適用可能な自動化信頼性パターン
アンチパターン
| パターン | 問題 | 修正方法 |
|---|---|---|
| 既存のカスタマイズを確認せずに同期 | 自動生成エントリがユーザーの手書きプロジェクト説明、featuredフラグ、カスタム順序を上書きする可能性があります。 | まず対象ファイルを読み込む。非標準構造を検出する。featured: true エントリについては全フィールドを保持する。新規または変更されたリポジトリのみアップサートする。 |
| すべてのリポジトリに対して無差別にスクリーンショットをキャプチャ | ライブデモのないリポジトリで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 パスを派生する。再利用のために同期状態に保存する。 |