# バッチ設計書 46-Pull Request Labeler（labeler.yml）

## 概要

本ドキュメントは、GitHub Actionsワークフロー「Pull Request Labeler」（labeler.yml）のバッチ設計書である。Pull Request作成時に変更されたファイルのパスに基づいて自動的にラベルを付与するワークフローについて記載する。

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

本ワークフローは、Pull Requestが作成されたときに、変更ファイルのパスパターンに基づいて自動的に適切なラベル（benchmark、build、core、doc、github、miscellaneous、mrbgems、oss-fuzz、tools）を付与する。

**業務上の目的・背景**：mrubyプロジェクトでは多数のPull Requestが作成されるため、変更の種類を一目で把握できるようにラベルを活用している。手動でのラベル付与は漏れや不整合が発生しやすいため、変更ファイルのパスに基づいて自動的にラベルを付与することで、Pull Requestのトリアージやレビュー優先度の判断を効率化する。sync-labels機能により、PRの変更内容が更新された際にラベルも自動的に同期される。

**バッチの実行タイミング**：Pull Request作成時（pull_request_targetイベント）に自動実行される。

**主要な処理内容**：
1. Pull Requestの変更ファイル一覧を取得する
2. `.github/labeler.yml`の定義に基づいて、変更ファイルパスとラベルルールをマッチングする
3. マッチしたラベルをPull Requestに付与する（sync-labels: trueにより不要なラベルは除去）

**前後の処理との関連**：本ワークフローは独立して実行される。ラベル定義は`.github/labeler.yml`で管理される。付与されたラベルは他のワークフローの条件分岐やPRフィルタリングに使用される可能性がある。

**影響範囲**：Pull Requestのラベル。変更ファイルに応じたラベルが自動的に設定・同期される。

## バッチ種別

自動化 / Pull Request管理 / CI（継続的インテグレーション）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（イベント駆動） |
| 実行時刻 | 該当なし（イベントトリガー） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | Pull Request作成時（pull_request_target） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHubリポジトリ | mrubyリポジトリがGitHub上に存在すること |
| ラベル定義 | `.github/labeler.yml`が存在すること |
| GITHUB_TOKEN | シークレットとしてGITHUB_TOKENが利用可能であること |

### 実行可否判定

GitHub Actionsのpull_request_targetイベントトリガーにより自動判定される。全てのPull Request作成イベントに対して実行される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| repo-token | string | Yes | secrets.GITHUB_TOKEN | GitHub APIアクセス用トークン |
| sync-labels | boolean | No | true | ラベルの同期を有効化（不要なラベルの自動除去） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .github/labeler.yml | YAML | ラベル付与ルールの定義ファイル |
| Pull Requestの変更ファイル | GitHub API | PRで変更されたファイルの一覧 |

### ラベル定義内容

`.github/labeler.yml`で定義されているラベルルールは以下の通り：

| ラベル名 | マッチングパターン |
|---------|-------------------|
| benchmark | `benchmark/**/*` |
| build | `Dockerfile`, `Doxyfile`, `Makefile`, `Rakefile`, `appveyor.yml`, `build_config.rb`, `build_config/**/*`, `docker-compose.yml`, `lib/**/*`, `minirake`, `tasks/**/*`, 各種設定ファイル |
| core | `include/**/*`, `mrblib/**/*`, `src/**/*`, `test/**/*` |
| doc | `CONTRIBUTING.md`, `LEGAL`, `LICENSE`, `NEWS`, `README.md`, `SECURITY.md`, `TODO.md`, `doc/**/*`, `examples/**/*` |
| github | `.github/**/*` |
| miscellaneous | `.editorconfig`, `.git-blame-ignore-revs`, `.gitattributes`, `.gitignore`, `AUTHORS`, `Gemfile`, `Gemfile.lock`, `mruby-source.gemspec` |
| mrbgems | `mrbgems/**/*` |
| oss-fuzz | `oss-fuzz/**/*` |
| tools | `tools/**/*` |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Pull Requestラベル | GitHub API | PRに付与されるラベル |
| GitHub Actionsログ | テキスト | ラベル付与処理の詳細ログ |

### 出力ファイル仕様

本ワークフローはファイル出力を行わない。結果はGitHub APIを通じてPull Requestのラベルとして反映される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし |
| 出力先 | Pull Requestのラベル |
| 文字コード | 該当なし |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. Pull Requestイベント検出
   └─ pull_request_targetイベントの発生を検知
2. ラベル付与処理
   └─ actions/labeler@v6がPRの変更ファイルを.github/labeler.ymlのルールと照合し、マッチしたラベルを付与
3. ラベル同期
   └─ sync-labels: trueにより、ルールに合致しなくなったラベルを自動的に除去
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始<br>pull_request_target] --> B[変更ファイル一覧取得<br>GitHub API]
    B --> C[labeler.ymlルールと照合]
    C --> D[マッチしたラベルを付与]
    D --> E{sync-labels有効}
    E -->|Yes| F[不要なラベルを除去]
    E -->|No| G[ワークフロー終了]
    F --> G
```

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

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

本ワークフローはデータベース操作を行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API権限エラー | GITHUB_TOKENの権限が不足している場合 | ワークフローの権限設定を確認する |
| - | ラベル定義エラー | labeler.ymlの構文エラー | labeler.ymlの構文を修正する |
| - | GitHub APIエラー | GitHub APIの一時的な障害 | GitHub Actionsを再実行する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 手動で再実行（GitHub Actions UI） |
| リトライ間隔 | 該当なし（手動） |
| リトライ対象エラー | 一時的なAPIエラー |

### 障害時対応

ラベル付与に失敗した場合は、GitHub Actionsのログからエラー原因を確認する。labeler.ymlの構文に問題がある場合は修正する。GITHUB_TOKENの権限不足の場合はワークフローの権限設定を確認する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（CI/CDパイプライン） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | Pull Requestの変更ファイル数に依存 |
| 目標処理時間 | 明示的な規定なし（高速に完了する想定） |
| メモリ使用量上限 | ubuntu-latestランナーのデフォルト（7GB RAM） |

## 排他制御

GitHub Actionsの標準動作により、同一PRに対する複数のワークフロー実行が発生する可能性がある。concurrencyの設定は定義されていないため、同時実行が許可されている。sync-labelsにより最終的な状態は整合的になる。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actionsの標準ログ（PRイベント情報） |
| 進捗ログ | ラベル処理中 | マッチングルール評価結果、付与/除去されたラベル |
| 終了ログ | ワークフロー終了時 | ラベル付与結果サマリー |
| エラーログ | エラー発生時 | APIエラー情報、設定ファイルパースエラー |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHubリポジトリの通知設定に従う |

## 備考

- actions/labeler@v6を使用している
- pull_request_targetイベントを使用しているため、フォークからのPRでも安全に動作する
- sync-labels: trueにより、PRの変更内容が変わった場合にラベルが自動的に同期される
- 権限設定として`contents: read`と`pull-requests: write`が必要
- 9カテゴリのラベル（benchmark, build, core, doc, github, miscellaneous, mrbgems, oss-fuzz, tools）が定義されている
- buildラベルのマッチングパターンは最も広範で、ビルド関連の多数のファイルパスを含む
