# バッチ設計書 14-nix.yml

## 概要

本ドキュメントは、GitHub Actions ワークフロー `nix.yml` の設計仕様を記載したバッチ設計書です。プッシュおよびプルリクエスト時にNix関連のチェック（Zigキャッシュハッシュ検証）を実行するワークフローの詳細を説明します。

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

このバッチは、コード変更時にZigの依存関係キャッシュハッシュが正しく更新されているかを検証します。Nix環境を使用してビルドの再現性を担保し、依存関係の整合性を自動的にチェックすることで、ビルドの一貫性と信頼性を確保します。

**業務上の目的・背景**：Ghosttyプロジェクトでは、Nixを使用して再現可能なビルド環境を提供しています。Zigの依存関係はハッシュベースで管理されており、依存関係の追加や更新時には対応するキャッシュハッシュの更新が必要です。本ワークフローは、開発者がハッシュの更新を忘れた場合に早期に検出し、ビルドの失敗やセキュリティリスクを防止します。

**バッチの実行タイミング**：プッシュおよびプルリクエスト時に自動実行されます。全てのブランチへのプッシュ、全てのプルリクエストが対象です。

**主要な処理内容**：
1. コードのチェックアウト
2. Nix環境のセットアップ
3. Cachixによるキャッシュ設定
4. Zigキャッシュハッシュの検証（check-zig-cache.sh）
5. 検証結果の集約と最終ステータス判定

**前後の処理との関連**：test.ymlなどの他のCIワークフローと並行して実行されます。本ワークフローが失敗した場合、PRはマージブロックされます。update-colorschemes.ymlなどで依存関係を更新した後のPRで特に重要なチェックとなります。

**影響範囲**：ビルドプロセスに直接影響はありませんが、検証失敗時はPRのマージがブロックされます。Nixを使用したビルド（nix build）の整合性を担保します。

## バッチ種別

CI/CD / 検証処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動 |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | push / pull_request |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| リポジトリ | ghostty-org/ghostty リポジトリでのみ実行（check-zig-cache-hashジョブ） |
| Nix環境 | Nixがインストール可能であること |

### 実行可否判定

- `check-zig-cache-hash` ジョブ：`github.repository == 'ghostty-org/ghostty'` の条件で公式リポジトリでのみ実行
- `required` ジョブ：常に実行され、依存ジョブの結果を集約

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| build.zig.zon | Zig設定 | Zig依存関係定義 |
| build.zig.zon.nix | Nix | Nix用ハッシュファイル |
| build.zig.zon.txt | テキスト | ハッシュリスト |
| build.zig.zon.json | JSON | JSON形式ハッシュ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions ステータス | ステータス | 検証結果（success/failure） |
| GITHUB_OUTPUT | テキスト | result, results変数 |

### 出力ファイル仕様

本ワークフローではファイル出力は行いません。

## 処理フロー

### 処理シーケンス

```
1. check-zig-cache-hashジョブ
   ├─ コードチェックアウト
   ├─ キャッシュセットアップ（/nix, /zig）
   ├─ Nixセットアップ
   ├─ Cachix設定
   └─ check-zig-cache.sh実行
2. requiredジョブ（依存: check-zig-cache-hash）
   ├─ 依存ジョブ結果の収集
   ├─ failure/cancelledチェック
   └─ 最終ステータス出力
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[check-zig-cache-hash]
    B --> C[コードチェックアウト]
    C --> D[キャッシュセットアップ]
    D --> E[Nixセットアップ]
    E --> F[Cachix設定]
    F --> G[check-zig-cache.sh実行]
    G --> H{検証成功?}
    H -->|成功| I[required: success]
    H -->|失敗| J[required: failed]
    I --> K[ワークフロー終了]
    J --> K
```

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

本ワークフローではデータベース操作は行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ハッシュ不整合 | Zigキャッシュハッシュが不正 | check-zig-cache.sh --update を実行 |
| - | Nixセットアップ失敗 | Nixインストールエラー | ログを確認し再実行 |
| - | Cachix認証エラー | トークン無効 | シークレットを確認 |

### リトライ仕様

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

### 障害時対応

1. エラーログでハッシュ不整合の詳細を確認
2. ローカルで `nix develop -c ./nix/build-support/check-zig-cache.sh --update` を実行
3. 更新されたハッシュファイルをコミット
4. 再プッシュして検証を再実行

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/イベント |
| 目標処理時間 | 10分以内 |
| メモリ使用量上限 | 指定なし |

## 排他制御

concurrencyグループ `${{ github.workflow }}-${{ github.ref_name != 'main' && github.ref || github.run_id }}` により、同一ブランチでの重複実行を制御します。mainブランチ以外では同一ブランチの実行をキャンセルし、mainブランチでは各実行を個別に扱います。`cancel-in-progress: true` により、古い実行はキャンセルされます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actions標準ログ |
| 検証ログ | ハッシュ検証時 | check-zig-cache.shの出力 |
| 結果ログ | required判定時 | result, results値 |
| エラーログ | 失敗時 | "One or more required build workflows failed" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHub通知・PRステータス |

## 備考

- requiredジョブは「Required Checks: Nix」として設定され、PRマージの必須条件となる
- Cachixの `useDaemon: false` 設定は短時間ジョブでのデーモン失敗を回避するため
- namespace-profile-ghostty-smランナーを使用
- ZIG_LOCAL_CACHE_DIR: /zig/local-cache
- ZIG_GLOBAL_CACHE_DIR: /zig/global-cache
