# バッチ設計書 5-Release

## 概要

本ドキュメントは、Releaseバッチ（release.yml）の設計仕様を記載したものである。このバッチは、mainブランチへのプッシュ時にchangesetsを使用してnpmパッケージのリリースを自動化するCI/CDバッチである。

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

**業務上の目的・背景**：@liam-hq/cliなどの公開npmパッケージを継続的にリリースするため、mainブランチへのマージをトリガーとした自動リリースプロセスが必要である。本バッチは、changeset/actionを使用して、未リリースの変更がある場合はRelease PRを作成し、Release PRがマージされた場合はnpmへの公開を実行する。Trusted Publisher設定により、セキュアな認証でnpmにパッケージを公開する。

**バッチの実行タイミング**：mainブランチへのプッシュ時（PR merge含む）に自動実行される。

**主要な処理内容**：
1. GitHub App Tokenを生成
2. コードをチェックアウトし、pnpm環境をセットアップ
3. npmを最新版に更新（Trusted Publishing対応のため）
4. changesets/actionでRelease PR作成またはnpmパブリッシュを実行
5. パッケージ公開成功時、released_package_test.ymlをトリガー
6. 失敗時はSlackに通知

**前後の処理との関連**：パッケージ公開成功後、Released Package Test（released_package_test.yml）が自動的にトリガーされ、公開されたパッケージの動作検証が行われる。

**影響範囲**：npmレジストリ（@liam-hq/cli等）、GitHubリリース、Slackチャンネル

## バッチ種別

CI/CD / パッケージリリース

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動 |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | mainブランチへのpush |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| CHANGESET_CI_TRIGGER_APP_ID | GitHub App IDがvarsに設定されていること |
| CHANGESET_CI_TRIGGER_APP_PRIVATE_KEY | GitHub App秘密鍵がSecretsに設定されていること |
| npmjs.com Trusted Publisher | release.ymlがTrusted Publisherとして登録されていること |
| SLACK_CLI_CI_WEBHOOK_URL | Slack Webhook URLがSecretsに設定されていること |

### 実行可否判定

- mainブランチへのpush時に自動実行
- changesets（.changeset/）に未リリースの変更がある場合はRelease PR作成
- Release PRがマージされている場合はnpm publish実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| - | - | - | - | 入力パラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .changeset/ | Markdown | 変更セット定義 |
| package.json | JSON | パッケージバージョン情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| npmレジストリ | npm package | 公開パッケージ |
| GitHub Releases | Release | リリースノート |
| GitHub PR | API | Release PR（未リリース変更がある場合） |
| Slack通知 | JSON | 失敗時の通知 |

### 出力ファイル仕様

ファイル出力なし（npmレジストリへの公開）

## 処理フロー

### 処理シーケンス

```
1. GitHub App Token生成
   └─ actions/create-github-app-token@v2.1.4
   └─ contents:write, pull-requests:write権限
2. コードチェックアウト
   └─ actions/checkout@v4.3.0
   └─ App Tokenを使用
3. pnpm環境セットアップ
   └─ .github/actions/pnpm-setup
4. npm更新
   └─ npm update -g npm
   └─ Trusted Publishing対応（npm 11.5.1+必要）
5. changesets/action実行
   └─ Release PR作成（未リリース変更がある場合）
   └─ npm publish（Release PRマージ済みの場合）
   └─ pnpm run releaseコマンド使用
6. パッケージ公開成功時
   └─ released_package_test.ymlをAPI経由でトリガー
   └─ 60秒の遅延を設定
   └─ バージョン情報を渡す
7. 失敗時Slack通知
   └─ tokorom/action-slack-incoming-webhook@v1.3.0
```

### フローチャート

```mermaid
flowchart TD
    A[mainへpush] --> B[GitHub App Token生成]
    B --> C[コードチェックアウト]
    C --> D[pnpm環境セットアップ]
    D --> E[npm更新]
    E --> F[changesets/action実行]
    F --> G{動作モード?}
    G -->|未リリース変更あり| H[Release PR作成/更新]
    G -->|Release PRマージ済| I[npm publish実行]
    I --> J{公開成功?}
    J -->|はい| K[released_package_testトリガー]
    J -->|いいえ| L[Slack通知]
    H --> M[バッチ終了]
    K --> M
    L --> M
```

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | npm publish失敗 | 認証エラー/ネットワークエラー | Trusted Publisher設定確認 |
| - | changesets失敗 | 変更セット形式エラー | .changeset/の内容確認 |
| - | Token生成失敗 | GitHub App設定エラー | App設定/Secrets確認 |

### リトライ仕様

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

### 障害時対応

- npm publish失敗時：Slack通知を確認し、原因特定後に再実行（mainへの空コミット）
- ワークフロー全体失敗時：GitHub Actionsログを確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし |
| コミットタイミング | changesets/actionが管理 |
| ロールバック条件 | npm unpublish（24時間以内） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/push |
| 目標処理時間 | 15分以内（timeout-minutes: 15） |
| メモリ使用量上限 | GitHub Actions標準ランナー制限内 |

## 排他制御

- concurrencyグループ: `${{ github.workflow }}-${{ github.ref }}`
- cancel-in-progress: false（リリース処理は中断しない）

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各ステップ開始時 | ステップ名 |
| 進捗ログ | 処理中 | changesets出力、npm publish結果 |
| 終了ログ | バッチ終了時 | 公開結果 |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | failure | Slack (#cli-ci チャンネル) |
| 処理時間 | 15分 | GitHub Actionsタイムアウト |

## 備考

- ワークフローファイル名「release.yml」はnpmjs.comのTrusted Publisher設定に登録されている
- ファイル名を変更する場合は、npmjs.comのTrusted Publisher設定も更新が必要
- 例：https://www.npmjs.com/package/@liam-hq/cli/access
- npm 11.5.1以上でTrusted Publishing対応（id-token: write権限を使用）
- cancel-in-progress: falseにより、リリース処理の途中キャンセルを防止
- パッケージ公開後60秒待機してからテストをトリガー（npm CDN反映待ち）
