# バッチ設計書 20-vouch-sync-codeowners.yml

## 概要

本ドキュメントは、GitHub Actions ワークフロー `vouch-sync-codeowners.yml` の設計仕様を記載したバッチ設計書です。CODEOWNERSファイルをVouchデータと同期するワークフローの詳細を説明します。

### 本バッチの処理概要

このバッチは、Ghosttyプロジェクトの信頼システム（Vouch）で管理されている信頼済みユーザーの情報を、GitHubのCODEOWNERSファイルに自動的に同期します。これにより、信頼されたコントリビューターが適切なコードレビュー権限を持つようになります。

**業務上の目的・背景**：GitHubのCODEOWNERSファイルは、特定のファイルやディレクトリに対するコードオーナーを定義し、PRレビューの自動割り当てに使用されます。Vouchシステムで信頼されたユーザーをCODEOWNERSに反映することで、信頼管理とコードレビュー権限を一元化し、手動管理の負担を削減します。

**バッチの実行タイミング**：毎週月曜日の0時（UTC）にスケジュール実行されます。また、workflow_dispatchによる手動実行も可能であり、即座の同期が必要な場合に対応できます。

**主要な処理内容**：
1. Vouchデータの読み込み
2. CODEOWNERSファイルの生成/更新
3. 変更がある場合はPRの作成
4. 即座のマージ

**前後の処理との関連**：vouch-manage-by-issue.ymlやvouch-manage-by-discussion.ymlで更新されたVouchデータを定期的にCODEOWNERSに反映します。同じconcurrencyグループ（vouch-manage）を共有し、データの整合性を保証します。

**影響範囲**：リポジトリのCODEOWNERSファイルが更新されます。これにより、PRの自動レビュー割り当てやブランチ保護ルールに影響を与える可能性があります。

## バッチ種別

定期実行 / データ同期

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 週次 |
| 実行時刻 | 00:00 UTC |
| 実行曜日 | 月曜日 |
| 実行日 | 毎週月曜日 |
| トリガー | cron / 手動（workflow_dispatch） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Vouchデータ存在 | リポジトリ内にVouchデータファイルが存在すること |
| GitHub App | VOUCH_APP_IDとVOUCH_APP_PRIVATE_KEYが設定されていること |

### 実行可否判定

スケジュールまたは手動トリガーで常に実行されます。Vouchデータに変更がない場合でも実行され、CODEOWNERSファイルが既に最新の場合はPRは作成されません。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| repo | string | Yes | ${{ github.repository }} | 対象リポジトリ |
| pull-request | string | Yes | "true" | PR作成の有無 |
| merge-immediately | string | Yes | "true" | 即座マージの有無 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Vouch データ | ファイル | 信頼済みユーザー一覧 |
| CODEOWNERS | ファイル | 現在のコードオーナー設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| CODEOWNERS | ファイル | 更新されたコードオーナー設定 |
| Pull Request | GitHub PR | 変更を含むPR（即座にマージ） |
| GitHub Actions ログ | テキスト | 処理結果 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | CODEOWNERS（または.github/CODEOWNERS） |
| 出力先 | リポジトリルートまたは.githubディレクトリ |
| 形式 | GitHub CODEOWNERS形式 |

## 処理フロー

### 処理シーケンス

```
1. GitHub App トークン生成
   └─ actions/create-github-app-token でアプリトークンを取得
2. コードチェックアウト
   └─ アプリトークンを使用してリポジトリをチェックアウト
3. CODEOWNERS同期アクション実行
   └─ mitchellh/vouch/action/sync-codeowners
   ├─ Vouchデータの読み込み
   ├─ CODEOWNERSファイルの生成/更新
   ├─ 変更がある場合はPR作成
   └─ 即座マージ
```

### フローチャート

```mermaid
flowchart TD
    A[スケジュール/手動実行] --> B[ワークフロー開始]
    B --> C[App トークン生成]
    C --> D[コードチェックアウト]
    D --> E[Vouchデータ読み込み]
    E --> F[CODEOWNERS生成]
    F --> G{変更あり?}
    G -->|なし| H[スキップ]
    G -->|あり| I[PR作成]
    I --> J[即座マージ]
    J --> K[ワークフロー終了]
    H --> K
```

## データベース操作仕様

本ワークフローではデータベース操作は行いません。Vouchデータとコードオーナー設定はリポジトリ内のファイルとして管理されます。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 認証エラー | App トークン生成失敗 | シークレット設定を確認 |
| - | データ不整合 | Vouchデータ形式エラー | Vouchデータを確認 |
| - | マージ競合 | CODEOWNERSファイルの競合 | 手動で解決 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. GitHub Actions UIでエラーログを確認
2. VOUCH_APP_ID, VOUCH_APP_PRIVATE_KEY シークレットを確認
3. Vouchデータファイルの形式を確認
4. 競合がある場合は手動でCODEOWNERSを更新

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 全処理 |
| コミットタイミング | PR作成・マージ時 |
| ロールバック条件 | 手動でrevert PR作成可能 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/週 |
| 目標処理時間 | 5分以内 |
| メモリ使用量上限 | 指定なし |

## 排他制御

concurrencyグループ `vouch-manage` により、Vouch関連ワークフローの同時実行を制御します。`cancel-in-progress: false` により、実行中のワークフローはキャンセルされません。vouch-manage-by-issue.ymlおよびvouch-manage-by-discussion.ymlと同じconcurrencyグループを共有します。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actions標準ログ |
| 同期ログ | CODEOWNERS更新時 | 変更内容 |
| 終了ログ | ワークフロー終了時 | 処理結果とPR情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHub通知 |

## 備考

- mitchellh/vouch/action/sync-codeowners@v1.4.2 を使用
- GitHub App トークンを使用（VOUCH_APP_ID, VOUCH_APP_PRIVATE_KEY）
- namespace-profile-ghostty-xsmランナーで実行
- cron式: "0 0 * * 1"（毎週月曜日0時UTC）
- pull-request: "true" でPRを作成
- merge-immediately: "true" で即座にマージ
- 他のVouch管理ワークフローと同じconcurrencyグループを共有
- CODEOWNERSファイルの更新は、PRレビュー自動割り当てやブランチ保護に影響
