GitHub to WBS Sync

GitHub Issues、GitHub Projects v2、Pull Requestsを実作業の正として読み取り、 WBS向けデータへ一方向に正規化します。

• Web: Overview / WBS / Gantt / GitHub Data
• CLI: CSVまたはGoogle SheetsへWBS_IDを主キーとしてupsert

GitHubへの書き戻しは行いません。

Webアプリ

GitHubログイン

Web版は固定PATではなく、GitHub OAuthログインを使用します。

1. GitHubのSettings > Developer settings > OAuth AppsでOAuth Appを作成
2. Authorization callback URLへ次を設定

http://localhost:3000/api/auth/github/callback

3. .env.localを作成

GITHUB_OAUTH_CLIENT_ID=...
GITHUB_OAUTH_CLIENT_SECRET=...
AUTH_SECRET=32文字以上のランダム値

AUTH_SECRETの作成例:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

4. 起動

npm install
npm run dev

http://localhost:3000を開き、GitHubでログインします。 ログイン後、参照可能なrepositoryとProjects v2を画面から選択します。Project field名も同じ設定画面で変更できます。これらは暗号化セッションへ保存され、 Environment Variablesは使用しません。

GitHubのアクセストークンはAES-256-GCMで暗号化し、HttpOnly Cookieに保存します。 ブラウザJavaScriptや公開環境変数へは渡しません。ログアウト時にはGitHub側の OAuth tokenも失効させます。

Private repositoryの読み取りにはOAuthのrepo scopeが必要です。 Projects v2にはread:project、Organization情報にはread:orgを要求します。

ローカルtokenモード

OAuth Appが未設定でGITHUB_TOKENが利用可能な場合も、Web画面の Settingsから参照可能なrepositoryとProjects v2を動的に選択できます。

選択したrepository、Project、field名だけを署名付きHttpOnly Cookieへ保存します。 GITHUB_TOKENはサーバー側だけで使用し、ブラウザへ送信しません。このモードは ローカル動作確認とCLI互換用途を想定しています。共有環境ではOAuthを使用してください。

Vercel

VercelにはユーザーPATを保存しません。次のアプリ資格情報だけを暗号化された Environment Variablesへ登録します。

• GITHUB_OAUTH_CLIENT_ID
• GITHUB_OAUTH_CLIENT_SECRET
• AUTH_SECRET

OAuth Appはcallback URLを1つ持つため、ローカル用とVercel用を分ける運用を 推奨します。Vercel用OAuth Appには次を設定します。

https://your-app.vercel.app/api/auth/github/callback

Projects v2

Project連携は設定画面から選択します。未選択時はIssueとPRのみを同期します。 ダッシュボード右上のSettingsからrepository、Project、WBS_ID欠落時の処理、 Project field名をいつでも変更できます。

Start_DateとDue_Dateが設定されている場合、WebのWBSとGanttはその日付を 優先します。

API

• GET /api/health: 稼働確認
• GET /api/wbs: ログインユーザーの権限で取得したWBS JSON
• GET /api/auth/github/start: GitHub OAuth開始
• GET /api/auth/github/callback: OAuth callback
• POST /api/auth/logout: logoutとtoken失効

CLI同期

CLIとGitHub Actionsは従来どおりGITHUB_TOKENを使用できます。

Copy-Item wbs-sync.config.example.json wbs-sync.config.json
$env:GITHUB_TOKEN = gh auth token
npm run sync -- --config .\wbs-sync.config.json --dry-run
npm run sync -- --config .\wbs-sync.config.json

WBS_IDの優先順位

1. Project field WBS_ID
2. Issue body内のWBS_ID: xxx
3. Issue body内のWBS ID: xxx
4. Issue label wbs:xxx
5. Issue title先頭の[WBS-xxx]

未取得時の既定動作はskipです。auto-generateまたは use-issue-numberへ変更できます。

検証

npm run check
npm test
npm run build:cli
npm run build
npm audit

主な構成

• web/auth.ts: OAuth sessionの暗号化と検証
• app/api/auth/: OAuth開始、callback、logout
• src/github/client.ts: GitHub GraphQL取得とIssue/PR関連付け
• web/wbs-model.ts: Web表示用の階層、状態、工程、依存関係
• components/wbs-dashboard.tsx: 5ビューのUI
• src/wbs/: CSV、Google Sheetsのupsert