# バッチ設計書 18-vouch-manage-by-issue.yml

## 概要

本ドキュメントは、GitHub Actions ワークフロー `vouch-manage-by-issue.yml` の設計仕様を記載したバッチ設計書です。Issueコメントでのvouch/denounce/unvouchコマンドを処理するワークフローの詳細を説明します。

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

このバッチは、Ghosttyプロジェクトの信頼システム（Vouch）をIssueコメント経由で管理するための自動化処理を実行します。メンテナーやコントリビューターが特定のキーワードコマンドをIssueにコメントすることで、ユーザーの信頼状態を更新できます。

**業務上の目的・背景**：オープンソースプロジェクトでは、スパムや悪意のある貢献を防ぐために、コントリビューターの信頼性を管理する仕組みが重要です。Vouchシステムは、既存の信頼されたメンバーが新しいコントリビューターを「保証（vouch）」することで、コミュニティの健全性を維持します。本ワークフローは、この信頼管理をIssueコメントを通じて簡単に行えるようにします。

**バッチの実行タイミング**：イベント駆動で実行されます。Issueに新しいコメントが作成された時（issue_comment.created）にトリガーされます。

**主要な処理内容**：
1. Issueコメントの内容を解析
2. !vouch, !denounce, !unvouch キーワードの検出
3. 対象ユーザーの信頼状態の更新
4. 必要に応じてPRの作成と即座のマージ

**前後の処理との関連**：vouch-check-issue.yml や vouch-check-pr.yml と連携し、信頼状態に基づくアクセス制御を実現します。vouch-sync-codeowners.yml により、信頼状態がCODEOWNERSファイルに反映されます。

**影響範囲**：リポジトリ内の Vouch データファイルが更新されます。更新はPRとして作成され、merge-immediately設定により即座にマージされます。これにより、対象ユーザーの信頼状態が変更されます。

## バッチ種別

イベント駆動 / 信頼管理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動 |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | issue_comment.created |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| コメント作成 | Issueに新しいコメントが作成されること |
| コマンド存在 | コメント内に!vouch, !denounce, !unvouchキーワードが含まれること |
| 権限 | コマンド実行者が適切な権限を持つこと |

### 実行可否判定

issue_comment.created イベントで常にトリガーされますが、実際のコマンド処理はmitchellh/vouch/action/manage-by-issueアクション内で行われます。キーワードが含まれないコメントは無視されます。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| repo | string | Yes | ${{ github.repository }} | 対象リポジトリ |
| issue-id | number | Yes | ${{ github.event.issue.number }} | Issue番号 |
| comment-id | number | Yes | ${{ github.event.comment.id }} | コメントID |
| vouch-keyword | string | Yes | "!vouch" | 保証コマンドのキーワード |
| denounce-keyword | string | Yes | "!denounce" | 非難コマンドのキーワード |
| unvouch-keyword | string | Yes | "!unvouch" | 保証取消コマンドのキーワード |
| pull-request | string | Yes | "true" | PR作成の有無 |
| merge-immediately | string | Yes | "true" | 即座マージの有無 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| github.event.issue | オブジェクト | Issueイベントデータ |
| github.event.comment | オブジェクト | コメントイベントデータ |
| Vouch データ | ファイル | リポジトリ内の信頼データ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Vouch データファイル | ファイル | 更新された信頼データ |
| Pull Request | GitHub PR | 変更を含むPR（即座にマージ） |
| GitHub Actions ログ | テキスト | 処理結果 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | Vouchシステムで管理されるデータファイル |
| 出力先 | リポジトリ内 |
| 形式 | Vouchアクションで定義された形式 |

## 処理フロー

### 処理シーケンス

```
1. GitHub App トークン生成
   └─ actions/create-github-app-token でアプリトークンを取得
2. コードチェックアウト
   └─ アプリトークンを使用してリポジトリをチェックアウト
3. Vouch管理アクション実行
   └─ mitchellh/vouch/action/manage-by-issue
   ├─ コメント内容の解析
   ├─ キーワードの検出
   ├─ 信頼状態の更新
   ├─ PR作成
   └─ 即座マージ
```

### フローチャート

```mermaid
flowchart TD
    A[コメント作成] --> B[ワークフロー開始]
    B --> C[App トークン生成]
    C --> D[コードチェックアウト]
    D --> E[コメント解析]
    E --> F{キーワード検出?}
    F -->|なし| G[スキップ]
    F -->|!vouch| H[ユーザー保証]
    F -->|!denounce| I[ユーザー非難]
    F -->|!unvouch| J[保証取消]
    H --> K[PR作成]
    I --> K
    J --> K
    K --> L[即座マージ]
    L --> M[ワークフロー終了]
    G --> M
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 認証エラー | App トークン生成失敗 | シークレット設定を確認 |
| - | 権限エラー | コマンド実行権限なし | 実行者の権限を確認 |
| - | 形式エラー | コマンド形式が不正 | コマンド構文を確認 |

### リトライ仕様

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

### 障害時対応

1. GitHub Actions UIでエラーログを確認
2. VOUCH_APP_ID, VOUCH_APP_PRIVATE_KEY シークレットを確認
3. コマンド構文とターゲットユーザーを確認
4. 手動でVouchデータを更新

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

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

## パフォーマンス要件

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

## 排他制御

concurrencyグループ `vouch-manage` により、Vouch管理ワークフローの同時実行を制御します。`cancel-in-progress: false` により、実行中のワークフローはキャンセルされません。これにより、複数のVouchコマンドが競合することを防止します。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actions標準ログ |
| 処理ログ | コマンド処理時 | 検出されたコマンドと対象ユーザー |
| 終了ログ | ワークフロー終了時 | 処理結果とPR情報 |

## 監視・アラート

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

## 備考

- mitchellh/vouch/action/manage-by-issue@v1.4.2 を使用
- GitHub App トークンを使用（VOUCH_APP_ID, VOUCH_APP_PRIVATE_KEY）
- namespace-profile-ghostty-xsmランナーで実行
- コマンドキーワード:
  - !vouch: ユーザーを保証
  - !denounce: ユーザーを非難
  - !unvouch: 保証を取り消し
- pull-request: "true" でPRを作成
- merge-immediately: "true" で即座にマージ
- vouch-manage-by-discussion.yml と同じconcurrencyグループを共有
