# バッチ設計書 8-beta.yml

## 概要

本ドキュメントは、OpenCodeプロジェクトのベータブランチ同期ワークフロー（beta.yml）の設計仕様を定義する。このワークフローは毎時beta.tsスクリプトを実行し、ベータラベルの付いたPRをベータブランチにマージする。

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

このワークフローは、GitHub Actionsのスケジュールトリガーで毎時実行され、beta.tsスクリプトを呼び出してベータブランチの同期を行う。ベータラベルが付与されたPRを自動的にdevブランチベースのベータブランチにマージし、ベータリリースの準備を自動化する。

**業務上の目的・背景**：ベータリリースに含めたい機能をPRに「beta」ラベルを付けるだけで自動的にベータブランチに統合できる。これにより、開発チームは手動でのブランチマージ作業から解放され、ベータテスト対象の機能を柔軟に制御できる。毎時実行することで、ラベル付与後すぐにベータビルドに反映される。

**バッチの実行タイミング**：毎時0分にスケジュール実行される。手動でのworkflow_dispatchトリガーも可能。

**主要な処理内容**：
1. リポジトリをフルチェックアウト（fetch-depth: 0）
2. Bun実行環境をセットアップ
3. Git committer設定（OpenCode App）
4. beta.tsスクリプトを実行

**前後の処理との関連**：beta.tsスクリプトを呼び出す。ベータブランチへのプッシュは、publish.ymlのベータチャンネルリリースをトリガーする可能性がある。

**影響範囲**：ベータブランチの更新、ベータラベルPRへのコメント投稿に影響を与える。

## バッチ種別

ブランチ管理 / スケジュール実行ラッパー

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 毎時 |
| 実行時刻 | 毎時0分 |
| 実行曜日 | 毎日 |
| 実行日 | 毎日 |
| トリガー | cron（0 * * * *）、手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| OPENCODE_APP_ID | OpenCode GitHub App IDがvarsに設定 |
| OPENCODE_APP_SECRET | OpenCode GitHub App SecretがSecretsに設定 |
| Bun | Bunランタイムが利用可能 |
| contents: write | リポジトリへの書き込み権限 |
| pull-requests: write | PRへのコメント書き込み権限 |

### 実行可否判定

ワークフローは常に実行される。beta.tsスクリプト内でベータラベルPRの有無をチェックし、0件の場合は処理をスキップする。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | ワークフロー引数なし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| gh pr list | JSON | ベータラベルPR一覧（beta.ts内） |
| origin/dev | gitブランチ | ベースブランチ（beta.ts内） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| origin/beta | gitブランチ | 更新されたベータブランチ |
| PR comments | テキスト | マージ失敗時の通知コメント |

### 出力ファイル仕様

ファイル出力なし。Git操作とGitHub API操作のみ。

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v4（fetch-depth: 0）

2. Bunセットアップ
   └─ .github/actions/setup-bun

3. Git committer設定
   └─ .github/actions/setup-git-committer
   └─ OpenCode App認証トークン取得

4. beta.tsスクリプト実行
   └─ bun script/beta.ts
   └─ GH_TOKEN環境変数設定
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[checkout fetch-depth:0]
    B --> C[setup-bun]
    C --> D[setup-git-committer]
    D --> E[bun script/beta.ts]
    E --> F{beta.ts成功?}
    F -->|Yes| G[ワークフロー終了]
    F -->|No| H[エラー終了]
```

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

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

本ワークフローはデータベース操作を行わない。Git操作とGitHub API操作のみ（beta.ts経由）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | App認証失敗 | OPENCODE_APP_ID/SECRET不正 | secrets/vars確認 |
| - | beta.tsエラー | PRマージ失敗 | beta.tsログ確認 |
| - | 権限エラー | write権限不足 | ワークフロー権限確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（次回スケジュール実行で再試行） |
| リトライ間隔 | 1時間（スケジュール間隔） |
| リトライ対象エラー | 全てのエラー |

### 障害時対応

1. App認証失敗：OPENCODE_APP_ID/SECRETの設定を確認
2. beta.tsエラー：ワークフローログからbeta.tsの出力を確認
3. 継続的失敗：手動でworkflow_dispatchを実行して調査

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | beta.ts参照 |
| コミットタイミング | beta.ts参照 |
| ロールバック条件 | beta.ts参照 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | PR数: 1-20件/実行 |
| 目標処理時間 | 5分以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

beta.ymlに明示的なconcurrency設定はないが、beta.tsがベータブランチへのforce pushを行うため、実質的に最後の実行結果が反映される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ワークフローログ | 全ステップ | GitHub Actionsログ |
| beta.tsログ | スクリプト実行時 | PR処理状況、サマリー |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 発生時 | GitHub Actions通知 |
| PRマージ失敗 | 発生時 | PRコメント経由で通知 |

## 備考

- fetch-depth: 0でフルヒストリーを取得（beta.tsでのgit操作に必要）
- setup-git-committerアクションでOpenCode GitHub App認証を使用
- GH_TOKEN環境変数はsetup-git-committerのoutput.tokenから設定
- beta.tsの詳細は「4-beta.ts」バッチ設計書を参照
- cron式「0 * * * *」は毎時0分（24回/日）の実行
- ベータラベルPRがない場合は"No team PRs to merge"で終了
