# バッチ設計書 12-ghalint

## 概要

本ドキュメントは、GitHub Actions ワークフロー「ghalint」の設計を定義するものである。GitHub Actionsワークフローファイルの構文エラーやセキュリティ上の問題を検出するリンターを実行し、CI/CDパイプラインの品質を維持するバッチ処理について記載する。

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

**業務上の目的・背景**：GitHub Actionsワークフローは、CI/CDパイプラインの中核を担う重要なインフラである。ワークフロー定義に構文エラーやセキュリティ上の問題が含まれると、ビルド失敗やセキュリティインシデントにつながる可能性がある。本バッチは、ghalintツールを使用してワークフローファイルを静的解析し、問題を早期に検出することで、安全で信頼性の高いCI/CDパイプラインを維持する。チェックサム検証による改ざん防止も実装されており、サプライチェーンセキュリティにも配慮している。

**バッチの実行タイミング**：Pull Request作成時、更新時、およびMerge Group実行時に自動実行される。ただし、ワークフローファイルに変更がある場合のみ実行される。

**主要な処理内容**：
1. paths-filterアクションを使用して.github/workflows配下のファイル変更を検出
2. 変更がある場合のみ、ghalintツールをダウンロード・検証
3. SHA256チェックサムによりghalintバイナリの整合性を検証
4. ghalint runコマンドでワークフローファイルをリント
5. 問題が検出された場合、CIを失敗させる

**前後の処理との関連**：本バッチは独立して動作する。他のCI/CDバッチ（Frontend CI、Database CI、Dependency Review等）と並列実行されるが、相互依存関係はない。

**影響範囲**：.github/workflows配下のYAML/YMLファイル全体

## バッチ種別

静的解析 / リント / セキュリティチェック

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | Pull Request / Merge Group（ワークフロー変更時のみ） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ワークフロー変更 | .github/workflows配下のファイルに変更があること |
| 権限 | contents: read、pull-requests: read が付与されていること |
| ネットワーク | ghalintバイナリのダウンロードが可能であること |

### 実行可否判定

setup-jobステップでpaths-filterを使用し、以下のパターンに一致するファイルの変更を検出：
- `.github/workflows/ghalint.yml`
- `.github/workflows/**/*.yml`
- `.github/workflows/**/*.yaml`

`has-changes`出力がtrueの場合のみghalintジョブが実行される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| GHALINT_VERSION | 文字列 | - | 1.5.1 | ghalintのバージョン（ハードコード） |
| expected_hash | 文字列 | - | e791009d... | 期待されるチェックサム（ハードコード） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .github/workflows/*.yml | YAML | 解析対象のワークフローファイル |
| .github/workflows/*.yaml | YAML | 解析対象のワークフローファイル |
| ghalint v1.5.1 | バイナリ | リンターツール |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions Log | テキスト | リント結果の詳細 |
| GitHub Checks | Status | CI実行結果（成功/失敗） |

### 出力ファイル仕様

ファイル出力は行わない。結果はGitHub Actions実行ログに出力される。

## 処理フロー

### 処理シーケンス

```
1. setup-job開始
   └─ チェックアウト（persist-credentials: false）

2. 変更検出
   └─ paths-filterでワークフローファイルの変更を検出

3. 変更有無判定
   └─ has-changes == 'true' の場合のみ続行

4. ghalintジョブ開始
   └─ チェックアウト

5. ghalintダウンロード
   └─ GitHub Releasesからv1.5.1をダウンロード

6. チェックサム検証
   └─ SHA256ハッシュを検証（不一致時は即時終了）

7. ghalint実行
   └─ ghalint runでワークフローをリント

8. 結果出力
   └─ リント結果に基づきステータスを設定
```

### フローチャート

```mermaid
flowchart TD
    A[PR/Merge Group イベント発生] --> B[setup-job: チェックアウト]
    B --> C[paths-filter: 変更検出]
    C --> D{ワークフロー変更あり?}
    D -->|なし| E[スキップ]
    D -->|あり| F[ghalintジョブ開始]
    F --> G[ghalint v1.5.1 ダウンロード]
    G --> H{チェックサム検証}
    H -->|不一致| I[エラー終了]
    H -->|一致| J[ghalint run 実行]
    J --> K{リント結果}
    K -->|問題あり| L[ステータス: 失敗]
    K -->|問題なし| M[ステータス: 成功]
    E --> N[バッチ終了]
    I --> N
    L --> N
    M --> N
```

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

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

データベース操作は行わない。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CHECKSUM_MISMATCH | 検証エラー | ghalintバイナリのハッシュ不一致 | 期待ハッシュ値の確認、バージョン更新 |
| DOWNLOAD_FAILED | ダウンロードエラー | ghalintのダウンロード失敗 | ネットワーク確認、手動再実行 |
| LINT_ERROR | リントエラー | ワークフローに問題検出 | 指摘箇所を修正してPR更新 |

### リトライ仕様

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

### 障害時対応

1. チェックサム不一致の場合：ghalintのバージョンと期待ハッシュ値の整合性を確認
2. ダウンロード失敗の場合：一時的なネットワーク問題の可能性があるため、手動で再実行
3. リントエラーの場合：指摘内容を確認し、ワークフローファイルを修正

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 20-30ファイル（ワークフロー数） |
| 目標処理時間 | setup-job: 3分、ghalint: 10分 |
| メモリ使用量上限 | GitHubランナー標準（7GB） |

## 排他制御

同一refに対する同時実行は許可されない。concurrency設定により、同一ワークフロー・同一refの実行が重複した場合、先行する実行がキャンセルされる（cancel-in-progress: true）。

```yaml
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
```

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | イベント種別、対象ブランチ |
| 進捗ログ | ダウンロード時 | ghalintバージョン、ダウンロードURL |
| 検証ログ | チェックサム検証時 | 期待ハッシュ、実際のハッシュ |
| 終了ログ | ghalint実行後 | リント結果 |
| エラーログ | エラー発生時 | エラー詳細メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行失敗 | 1回 | GitHub Checks UI |
| タイムアウト | setup-job: 3分、ghalint: 10分 | GitHub Checks UI |

## 備考

- ghalint v1.5.1を使用（ハードコードされたバージョン）
- 期待チェックサム: e791009d9361c8f0f0d2e2b9b67d428fe2dddc6694cbfec9954e2502a8e0e0ff
- サプライチェーン攻撃対策としてチェックサム検証を実施
- persist-credentials: falseによりクレデンシャルの永続化を防止
