# バッチ設計書 18-ecosystem-ci-trigger.yml

## 概要

本ドキュメントは、GitHub Actionsによるエコシステムci トリガーワークフロー `.github/workflows/ecosystem-ci-trigger.yml` のバッチ設計書である。PRコメント（`/ecosystem-ci run`）でVueエコシステムCIを手動トリガーする。

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

PRへのIssueコメントで `/ecosystem-ci run` コマンドが投稿された際に、Vueエコシステムの互換性テスト（ecosystem-ci）をトリガーするワークフローである。vuejsオーガニゼーションのメンバーのみが実行可能であり、権限チェック後にecosystem-ciリポジトリのワークフローをGitHub APIでディスパッチする。

**業務上の目的・背景**：Vue本体への変更がエコシステム（Nuxt、Vuetify、Vue Router等）に与える影響を事前検証するため、PRコメントから手動でエコシステムCIをトリガーできるようにする。リリース前の互換性検証を効率化し、破壊的変更の早期検出を実現する。

**バッチの実行タイミング**：PRに `/ecosystem-ci run` で始まるコメントが投稿された際に自動実行される。vuejsオーガニゼーションのメンバーによるコメントのみが有効。

**主要な処理内容**：
1. コメント投稿者のvuejsオーガニゼーションメンバーシップを確認する
2. メンバーの場合は+1リアクション、非メンバーの場合は-1リアクションを付与し、非メンバーの場合はエラーで終了する
3. PRのブランチ情報（ブランチ名、リポジトリ、コミットSHA）を取得する
4. コメントからテストスイート名を抽出する（省略時は全スイート実行）
5. ecosystem-ciリポジトリの `ecosystem-ci-from-pr.yml` ワークフローをディスパッチする

**前後の処理との関連**：本ワークフローは `vuejs/ecosystem-ci` リポジトリの `ecosystem-ci-from-pr.yml` ワークフローをトリガーする。トリガーされたワークフローがVueエコシステムの各プロジェクトに対してCIテストを実行する。ECOSYSTEM_CI_ACCESS_TOKENシークレットが必要。

**影響範囲**：vuejs/ecosystem-ciリポジトリのワークフロー実行に影響する。vuejs/coreリポジトリでのみ実行される。

## バッチ種別

CI/CD（エコシステム互換性テストトリガー）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（PRコメント時） |
| 実行時刻 | 指定なし（コメント投稿時） |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | issue_comment (created) |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actionsランナー | ubuntu-latestが利用可能であること |
| ECOSYSTEM_CI_ACCESS_TOKEN | ecosystem-ciリポジトリへのワークフローディスパッチ権限を持つトークン |
| vuejs/coreリポジトリ | vuejs/coreリポジトリであること |
| PRコンテキスト | コメントがPR（issue.pull_request）に紐づいていること |

### 実行可否判定

以下の3条件が全て満たされた場合のみ実行される：
1. `github.repository == 'vuejs/core'`（vuejs/coreリポジトリ）
2. `github.event.issue.pull_request`（PRに関連するコメント）
3. `startsWith(github.event.comment.body, '/ecosystem-ci run')`（コメントが `/ecosystem-ci run` で始まる）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| suite | 文字列 | No | '-'（全スイート） | `/ecosystem-ci run` の後に続くテストスイート名。省略時は全スイート実行 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| github.event.comment.body | 文字列 | PRコメント本文 |
| github.event.issue.number | 数値 | PR番号 |
| PR APIレスポンス | JSON | PRのブランチ情報（head.ref, head.repo.full_name, head.sha） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| コメントリアクション | GitHubリアクション | +1（許可）または-1（拒否） |
| workflow_dispatch | GitHub API | ecosystem-ciリポジトリへのワークフローディスパッチ |

### 出力ファイル仕様

ファイル出力なし。

## 処理フロー

### 処理シーケンス

```
1. ユーザー権限チェック
   ├─ コメント投稿者のvuejsオーガニゼーションメンバーシップを確認
   ├─ メンバーの場合: +1リアクション付与、処理続行
   └─ 非メンバーの場合: -1リアクション付与、エラー終了
2. PR情報取得
   └─ PR APIからブランチ名、リポジトリ名、コミットSHAを取得
3. ワークフローディスパッチ
   ├─ コメントからスイート名を抽出（/ecosystem-ci run 以降のテキスト）
   └─ ecosystem-ci リポジトリの ecosystem-ci-from-pr.yml をディスパッチ
       inputs: prNumber, branchName, repo, suite, commit
```

### フローチャート

```mermaid
flowchart TD
    A[PRコメント /ecosystem-ci run] --> B{vuejs/core & PR?}
    B -->|No| Z[スキップ]
    B -->|Yes| C[ユーザー権限チェック]
    C --> D{vuejsメンバー?}
    D -->|Yes| E[+1 リアクション]
    D -->|No| F[-1 リアクション]
    F --> G[エラー終了]
    E --> H[PR情報取得]
    H --> I[スイート名抽出]
    I --> J[ecosystem-ci ワークフロー ディスパッチ]
    J --> K[ワークフロー完了]
    Z --> K
    G --> K
```

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

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 権限エラー | vuejsオーガニゼーション非メンバーがコマンドを実行した場合 | vuejsメンバーに実行を依頼する |
| - | APIエラー | GitHub APIの呼び出しが失敗した場合 | ECOSYSTEM_CI_ACCESS_TOKENの有効性を確認する |
| - | ワークフローディスパッチ失敗 | ecosystem-ciリポジトリへのディスパッチが失敗した場合 | トークンの権限とリポジトリの存在を確認する |

### リトライ仕様

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

### 障害時対応

権限エラーの場合はvuejsメンバーに実行を依頼する。APIエラーの場合はECOSYSTEM_CI_ACCESS_TOKENの有効期限と権限を確認する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ジョブ |
| 目標処理時間 | 数秒（APIコールのみ） |
| メモリ使用量上限 | 最小限（APIコールのみ） |

## 排他制御

明示的な排他制御なし。同一PRに対して複数のecosystem-ciトリガーが並行実行される可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ユーザー検証ログ | 権限チェック時 | `Validate user: {username}` / `Allowed` or `Not allowed` |
| PR情報ログ | PR情報取得時 | `Get PR info: {owner}/{repo}#{number}` |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー実行結果 | 失敗時 | GitHubリポジトリの通知設定に依存 |

## 備考

- `actions/github-script@v8` を3つのステップで使用し、全てJavaScriptで実装されている
- メンバーシップチェックは `github.rest.orgs.checkMembershipForUser` API（ステータスコード204で判定）を使用する
- スイート名が空の場合はデフォルト値 `-` が設定され、ecosystem-ci側で全スイート実行と解釈される
- `ECOSYSTEM_CI_ACCESS_TOKEN` はGitHubシークレットとして管理され、ecosystem-ciリポジトリのワークフローディスパッチ権限を持つPATが必要
- ワークフローのディスパッチ先は `vuejs/ecosystem-ci` リポジトリの `ecosystem-ci-from-pr.yml` ワークフロー（mainブランチ）
