# バッチ設計書 21-vouch-check-issue.yml

## 概要

本ドキュメントは、GitHub Actions ワークフロー「vouch-check-issue.yml」の設計書です。新規または再オープンされたIssueに対してVouchシステムによるユーザー認証チェックを自動実行し、未認証ユーザーからのIssueを自動クローズする機能を提供します。

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

**業務上の目的・背景**：オープンソースプロジェクトにおいて、スパムや悪意のあるIssue投稿を防止するため、Vouch（保証）システムを導入しています。このワークフローは、既存の信頼されたコントリビューターによって「保証（vouch）」されていないユーザーからのIssue作成を検出し、自動的にクローズすることで、プロジェクトメンテナーの負担を軽減し、コミュニティの品質を維持します。Vouchシステムは、信頼のウェブ（Web of Trust）の概念に基づき、既存メンバーが新規参加者を保証することで、段階的にコミュニティへの参加を許可する仕組みです。

**バッチの実行タイミング**：Issueが新規作成（opened）または再オープン（reopened）された時点でイベント駆動により即座に実行されます。手動実行やスケジュール実行は行わず、完全にイベントベースで動作します。

**主要な処理内容**：
1. GitHub Appトークンの生成：Vouch専用のGitHub Appを使用して認証トークンを取得
2. Vouchチェックの実行：mitchellh/vouch/action/check-issueアクションを呼び出し、Issue作成者のVouchステータスを確認
3. 自動クローズ処理：未認証ユーザーのIssueを自動的にクローズし、理由を説明するコメントを追加

**前後の処理との関連**：本ワークフローは独立して動作しますが、vouch-manage-by-issue.ymlおよびvouch-manage-by-discussion.ymlワークフローと連携しています。これらの管理ワークフローで「!vouch」コマンドによりユーザーが保証されると、そのユーザーは次回以降のIssue作成時にチェックを通過できるようになります。また、vouch-sync-codeowners.ymlによりCODEOWNERSファイルとの同期が行われます。

**影響範囲**：本ワークフローはGitHub Issues機能に影響を与えます。未認証ユーザーのIssueがクローズされるため、新規コントリビューターは既存メンバーからの保証を得る必要があります。リポジトリの全Issueが対象となります。

## バッチ種別

イベント駆動 / アクセス制御 / 自動モデレーション

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント発生時 |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | issues イベント（opened, reopened） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub App設定 | VOUCH_APP_IDおよびVOUCH_APP_PRIVATE_KEYシークレットが設定されていること |
| Vouchデータ存在 | リポジトリにVouchデータ（.github/vouch/配下）が存在すること |
| Issueイベント発生 | Issueが新規作成または再オープンされること |

### 実行可否判定

Issueイベント（opened または reopened）が発生した場合に自動的に実行されます。特別な実行可否判定ロジックはありません。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| github.event.issue.number | number | Yes | - | イベント発生元のIssue番号 |
| secrets.VOUCH_APP_ID | string | Yes | - | GitHub App ID |
| secrets.VOUCH_APP_PRIVATE_KEY | string | Yes | - | GitHub App秘密鍵 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Issue | GitHub API | トリガーとなったIssue情報 |
| Vouchデータ | YAML/JSON | リポジトリ内のVouch保証データ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Issue | GitHub API | Issueのステータス更新（クローズ） |
| GitHub Issue Comment | GitHub API | 自動クローズ時の説明コメント |

### 出力ファイル仕様

本ワークフローはファイル出力を行いません。すべての出力はGitHub API経由で行われます。

## 処理フロー

### 処理シーケンス

```
1. ワークフロー開始
   └─ Issueのopened/reopenedイベントをトリガーとして開始

2. GitHub Appトークン生成
   └─ actions/create-github-app-tokenアクションを使用
   └─ VOUCH_APP_IDとVOUCH_APP_PRIVATE_KEYから認証トークンを生成

3. Vouchチェック実行
   └─ mitchellh/vouch/action/check-issueアクションを呼び出し
   └─ Issue番号を渡してチェックを実行
   └─ auto-close: true設定により未認証時は自動クローズ

4. 結果処理
   └─ 認証済み：処理終了（Issueはオープンのまま）
   └─ 未認証：Issueを自動クローズし、説明コメントを追加

5. ワークフロー終了
```

### フローチャート

```mermaid
flowchart TD
    A[Issueイベント発生] --> B[ワークフロー開始]
    B --> C[GitHub Appトークン生成]
    C --> D[check-issueアクション実行]
    D --> E{ユーザーがVouch済み?}
    E -->|Yes| F[処理終了]
    E -->|No| G[Issueを自動クローズ]
    G --> H[説明コメント追加]
    H --> F
```

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

### 操作別データベース影響一覧

本ワークフローは直接的なデータベース操作を行いません。GitHub APIを介してIssueステータスの更新のみを行います。

| 処理 | 対象 | 操作種別 | 概要 |
|-----|-----|---------|------|
| Vouchチェック | GitHub Issue | READ | Issue作成者情報の取得 |
| 自動クローズ | GitHub Issue | UPDATE | Issueステータスをクローズに変更 |
| コメント追加 | GitHub Issue Comment | CREATE | クローズ理由のコメント追加 |

### テーブル別操作詳細

データベース操作なし（GitHub API操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| AUTH_ERROR | 認証エラー | GitHub Appトークン生成失敗 | シークレット設定を確認 |
| API_ERROR | API通信エラー | GitHub API呼び出し失敗 | ワークフローを再実行 |
| VOUCH_DATA_ERROR | データエラー | Vouchデータの読み取り失敗 | Vouchデータの形式を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | GitHub Actionsデフォルト（なし） |
| リトライ間隔 | - |
| リトライ対象エラー | 手動再実行が必要 |

### 障害時対応

1. ワークフロー実行ログを確認し、エラー原因を特定
2. シークレット（VOUCH_APP_ID, VOUCH_APP_PRIVATE_KEY）の有効性を確認
3. 必要に応じてIssueを手動でクローズまたは再オープン
4. ワークフローを手動で再実行（Issueを再オープンすることでトリガー可能）

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | GitHub API呼び出し単位 |
| コミットタイミング | 各API呼び出し完了時 |
| ロールバック条件 | 手動対応が必要（自動ロールバックなし） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1件/実行（1 Issue） |
| 目標処理時間 | 30秒以内 |
| メモリ使用量上限 | ランナーデフォルト |

## 排他制御

本ワークフローには排他制御（concurrency）設定がありません。複数のIssueイベントが同時に発生した場合、それぞれ独立して並行実行されます。各実行は異なるIssueを対象とするため、競合は発生しません。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | ワークフロー名、Issue番号 |
| トークン生成ログ | トークン生成完了時 | トークン生成成功/失敗 |
| チェック結果ログ | Vouchチェック完了時 | Vouch状態、実行アクション |
| 終了ログ | ワークフロー終了時 | 最終ステータス |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHub Actions通知 |
| 実行時間 | 5分超過 | GitHub Actions通知 |

## 備考

- 本ワークフローはmitchellh/vouchアクション（v1.4.2）を使用
- ランナーはnamespace-profile-ghostty-xsmを使用（軽量ジョブ向け）
- actions/create-github-app-tokenはv2.2.1を使用
- auto-close設定により、未認証ユーザーのIssueは説明付きで自動クローズされる
