Harden GitHub sync dispatch errors

oiahoon · oiahoon · commit f8e3834b48ec · 2026-07-14T23:37:07.000+08:00
diff --git a/apps/web/.env.example b/apps/web/.env.example
@@ -30,5 +30,12 @@ NIKE_REFRESH_TOKEN=your_nike_refresh_token
 # Mapbox (for maps)
 NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token
 
+# GitHub Actions manual sync dispatcher (server-only)
+# Fine-grained token: repository oiahoon/running2.0, Actions permission set to read/write.
+GITHUB_ACTIONS_TRIGGER_TOKEN=your_fine_grained_github_token
+GITHUB_SYNC_REPOSITORY=oiahoon/running2.0
+GITHUB_SYNC_WORKFLOW_ID=sync-data.yml
+GITHUB_SYNC_REF=master
+
 # Development
 NODE_ENV=development
diff --git a/apps/web/src/app/api/sync/route.ts b/apps/web/src/app/api/sync/route.ts
@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { getDatabase } from '@/lib/database/connection'
+import type { SyncErrorCode } from '@/lib/syncErrors'
 
 type SourceSetting = {
   source: string
@@ -15,6 +16,17 @@ type SourceLog = {
   completed_at: string | null
 }
 
+class WorkflowDispatchError extends Error {
+  constructor(
+    message: string,
+    readonly code: SyncErrorCode,
+    readonly httpStatus: number
+  ) {
+    super(message)
+    this.name = 'WorkflowDispatchError'
+  }
+}
+
 function normalizeSourceId(sourceId: string): string {
   if (sourceId === 'strava') return sourceId
   const prefix = sourceId.split('_')[0]
@@ -32,7 +44,11 @@ function toWorkflowBoolean(value: unknown) {
 async function triggerSyncWorkflow(body: Record<string, unknown>) {
   const token = process.env.GITHUB_ACTIONS_TRIGGER_TOKEN
   if (!token) {
-    throw new Error('Manual sync trigger is not configured. Set GITHUB_ACTIONS_TRIGGER_TOKEN in Vercel.')
+    throw new WorkflowDispatchError(
+      'Manual sync is not configured.',
+      'sync_not_configured',
+      503
+    )
   }
 
   const repository = getGitHubRepo()
@@ -58,8 +74,55 @@ async function triggerSyncWorkflow(body: Record<string, unknown>) {
   })
 
   if (!response.ok) {
-    const detail = await response.text().catch(() => '')
-    throw new Error(`GitHub workflow dispatch failed (${response.status}): ${detail || response.statusText}`)
+    const requestId = response.headers.get('x-github-request-id')
+    console.error('GitHub workflow dispatch rejected', {
+      status: response.status,
+      requestId,
+      repository,
+      workflowId,
+      ref,
+    })
+
+    if (response.status === 401) {
+      throw new WorkflowDispatchError(
+        'Manual sync authorization is invalid.',
+        'github_auth_invalid',
+        503
+      )
+    }
+    if (response.status === 403) {
+      throw new WorkflowDispatchError(
+        'Manual sync authorization cannot dispatch this workflow.',
+        'github_permission_denied',
+        503
+      )
+    }
+    if (response.status === 404) {
+      throw new WorkflowDispatchError(
+        'The configured sync workflow was not found.',
+        'workflow_not_found',
+        503
+      )
+    }
+    if (response.status === 422) {
+      throw new WorkflowDispatchError(
+        'The configured sync workflow, ref, or inputs are invalid.',
+        'workflow_config_invalid',
+        502
+      )
+    }
+    if (response.status >= 500) {
+      throw new WorkflowDispatchError(
+        'GitHub is temporarily unavailable.',
+        'github_unavailable',
+        502
+      )
+    }
+    throw new WorkflowDispatchError(
+      'The sync workflow could not be queued.',
+      'dispatch_failed',
+      502
+    )
   }
 
   return {
@@ -168,8 +231,14 @@ export async function POST(request: NextRequest) {
     )
   } catch (error) {
     console.error('Failed to sync data sources:', error)
+    if (error instanceof WorkflowDispatchError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.httpStatus }
+      )
+    }
     return NextResponse.json(
-      { error: error instanceof Error ? error.message : 'Failed to sync data sources' },
+      { error: 'Failed to sync data sources', code: 'dispatch_failed' satisfies SyncErrorCode },
       { status: 500 }
     )
   }
diff --git a/apps/web/src/app/data-sources/page.tsx b/apps/web/src/app/data-sources/page.tsx
@@ -2,6 +2,7 @@
 
 import { useEffect, useMemo, useState } from 'react'
 import { useI18n } from '@/lib/i18n'
+import { readSyncError } from '@/lib/syncErrors'
 
 interface DataSourceType {
   id: string
@@ -69,8 +70,7 @@ export default function DataSourcesPage() {
         body: JSON.stringify({ sources: ['strava'] }),
       })
       if (!response.ok) {
-        const data = await response.json().catch(() => ({}))
-        throw new Error(data?.error || t('sync.manualFailed'))
+        throw new Error(await readSyncError(response, t))
       }
       const data = await response.json().catch(() => ({}))
       setMessage(data?.message || t('sources.syncQueued'))
diff --git a/apps/web/src/app/sync/page.tsx b/apps/web/src/app/sync/page.tsx
@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { ArrowPathIcon } from '@heroicons/react/24/outline'
 import { useI18n } from '@/lib/i18n'
+import { readSyncError } from '@/lib/syncErrors'
 
 interface SyncRecord {
   id: string
@@ -90,8 +91,7 @@ export default function SyncPage() {
         body: JSON.stringify({ sources: ['strava'] }),
       })
       if (!response.ok) {
-        const data = await response.json().catch(() => ({}))
-        throw new Error(data?.error || t('sync.manualFailed'))
+        throw new Error(await readSyncError(response, t))
       }
       const data = await response.json().catch(() => ({}))
       setNotice(data?.message ? t('sync.refreshAfterDeploy', { message: data.message }) : t('sync.queued'))
diff --git a/apps/web/src/lib/i18n.tsx b/apps/web/src/lib/i18n.tsx
@@ -341,6 +341,13 @@ const dictionaries: Record<Locale, Record<string, string>> = {
     'sync.status.failed': 'Failed',
     'sync.status.running': 'Running',
     'sync.status.error': 'Error',
+    'sync.error.notConfigured': 'Manual sync is not configured. Ask an administrator to add the GitHub credential.',
+    'sync.error.githubAuthInvalid': 'Manual sync authorization has expired. Ask an administrator to refresh the GitHub credential.',
+    'sync.error.githubPermissionDenied': 'The GitHub credential cannot run this workflow. It needs Actions write access for this repository.',
+    'sync.error.workflowNotFound': 'The configured GitHub sync workflow could not be found.',
+    'sync.error.workflowConfigInvalid': 'The GitHub sync workflow, branch, or inputs are configured incorrectly.',
+    'sync.error.githubUnavailable': 'GitHub is temporarily unavailable. Try again shortly.',
+    'sync.error.dispatchFailed': 'The sync workflow could not be queued. Try again.',
     'sync.workflow': 'Workflow',
     'sync.workflow1': '1. Refresh latest source status',
     'sync.workflow2': '2. Queue GitHub Actions sync',
@@ -670,6 +677,13 @@ const dictionaries: Record<Locale, Record<string, string>> = {
     'sync.status.failed': '失败',
     'sync.status.running': '运行中',
     'sync.status.error': '错误',
+    'sync.error.notConfigured': '手动同步尚未配置，请联系管理员添加 GitHub 凭据。',
+    'sync.error.githubAuthInvalid': '手动同步授权已失效，请联系管理员刷新 GitHub 凭据。',
+    'sync.error.githubPermissionDenied': 'GitHub 凭据无法运行此工作流，需要此仓库的 Actions 写入权限。',
+    'sync.error.workflowNotFound': '未找到已配置的 GitHub 同步工作流。',
+    'sync.error.workflowConfigInvalid': 'GitHub 同步工作流、分支或输入配置有误。',
+    'sync.error.githubUnavailable': 'GitHub 暂时不可用，请稍后重试。',
+    'sync.error.dispatchFailed': '无法将同步工作流加入队列，请重试。',
     'sync.workflow': '工作流',
     'sync.workflow1': '1. 刷新最新来源状态',
     'sync.workflow2': '2. 排队执行 GitHub Actions 同步',
@@ -999,6 +1013,13 @@ const dictionaries: Record<Locale, Record<string, string>> = {
     'sync.status.failed': '失敗',
     'sync.status.running': '実行中',
     'sync.status.error': 'エラー',
+    'sync.error.notConfigured': '手動同期が設定されていません。管理者に GitHub 認証情報の追加を依頼してください。',
+    'sync.error.githubAuthInvalid': '手動同期の認証期限が切れています。管理者に GitHub 認証情報の更新を依頼してください。',
+    'sync.error.githubPermissionDenied': 'GitHub 認証情報でこのワークフローを実行できません。このリポジトリの Actions 書き込み権限が必要です。',
+    'sync.error.workflowNotFound': '設定された GitHub 同期ワークフローが見つかりません。',
+    'sync.error.workflowConfigInvalid': 'GitHub 同期ワークフロー、ブランチ、または入力の設定が正しくありません。',
+    'sync.error.githubUnavailable': 'GitHub は一時的に利用できません。しばらくしてから再試行してください。',
+    'sync.error.dispatchFailed': '同期ワークフローをキューに追加できませんでした。再試行してください。',
     'sync.workflow': 'ワークフロー',
     'sync.workflow1': '1. 最新ソース状態を更新',
     'sync.workflow2': '2. GitHub Actions 同期をキュー',
diff --git a/apps/web/src/lib/syncErrors.ts b/apps/web/src/lib/syncErrors.ts
@@ -0,0 +1,34 @@
+export type SyncErrorCode =
+  | 'sync_not_configured'
+  | 'github_auth_invalid'
+  | 'github_permission_denied'
+  | 'workflow_not_found'
+  | 'workflow_config_invalid'
+  | 'github_unavailable'
+  | 'dispatch_failed'
+
+const errorMessageKeys: Record<SyncErrorCode, string> = {
+  sync_not_configured: 'sync.error.notConfigured',
+  github_auth_invalid: 'sync.error.githubAuthInvalid',
+  github_permission_denied: 'sync.error.githubPermissionDenied',
+  workflow_not_found: 'sync.error.workflowNotFound',
+  workflow_config_invalid: 'sync.error.workflowConfigInvalid',
+  github_unavailable: 'sync.error.githubUnavailable',
+  dispatch_failed: 'sync.error.dispatchFailed',
+}
+
+function isSyncErrorCode(value: unknown): value is SyncErrorCode {
+  return typeof value === 'string' && Object.hasOwn(errorMessageKeys, value)
+}
+
+export async function readSyncError(
+  response: Response,
+  translate: (key: string) => string
+) {
+  const payload = await response.json().catch(() => ({})) as {
+    code?: unknown
+    error?: string
+  }
+  const messageKey = isSyncErrorCode(payload.code) ? errorMessageKeys[payload.code] : undefined
+  return messageKey ? translate(messageKey) : payload.error || translate('sync.manualFailed')
+}
diff --git a/docs/agentic/sync-ops.md b/docs/agentic/sync-ops.md
@@ -20,6 +20,11 @@ Manual sync was verified end-to-end on 2026-04-30 after refreshing the GitHub di
 - The workflow committed data update `9c086bfbdb153cac2b2f49aad0d5a7408a1b7a86`.
 - Production `/api/sync/history` reflected the new sync log at `2026-04-30T12:21:33.379Z`.
 
+Manual sync was reverified on 2026-07-14 after rotating the expired GitHub dispatch token:
+- `POST https://run2.miaowu.org/api/sync` returned `202` with structured `queued` state.
+- GitHub Actions run `29344918816` completed successfully from `workflow_dispatch`.
+- The dispatcher now maps GitHub authorization and workflow configuration failures to stable error codes, without returning raw upstream response bodies to the browser.
+
 ## Runtime Sync
 
 - Direct Strava executor: `apps/web/src/app/api/sync/strava/route.ts`
