devops-pipeline

DevOps パイプライン

プロジェクトの種類に合わせた包括的な DevOps 品質ゲートを実装します。シフトレフトの考え方に基づき、できるだけ多くのチェックを pre-commit でローカル実行します。これにより、開発者はすぐにフィードバックを得られ、CI は主なゲートではなくセーフティネットとして機能します。

基本原則：開発者のマシンで実行できるチェックは、そこで実行します。GitHub Actions では、ノートパソコンでは実行できないもの（バージョンのマトリックステスト、シークレットが必要なスキャン、デプロイ、カバレッジの公開）と、フックがバイパスされていないことを確認する低コストのジョブのみを実行します。

チェックの振り分け表

各チェックは、必ずいずれか1つのレーンに割り当てます。この表を唯一の基準とします。ワークフローのステップ2と3、リファレンスファイル、およびこのスキルが生成する設定は、すべてこの表に従う必要があります。

レーン	時間の目安	実行する内容
pre-commit ステージ（コミットごと）	< 10s、変更されたファイルのみ	フォーマット、Lint、型チェック、オフラインのセキュリティスキャン、高速なユニットテスト、コンパイル／インポートチェック
pre-push ステージ（プッシュごと）	< 60s、リポジトリ全体	テストスイート全体、CLI E2E、カバレッジしきい値、時間のかかる Lint ルールセット
GitHub Actions	分単位で課金	バージョンのマトリックステスト、シークレットが必要なスキャン、カバレッジのアップロード、デプロイ／リリース、バイパスガード

前のレーンで実行できるチェックを、後のレーンで再実行してはいけません。プッシュごとに CI がフック一式を再実行することは、このスキルで防ぐべき問題です。

エージェントのコンテキスト予算内に収めるため、この SKILL ではテンプレートを短く保ち、言語固有の設定、ワークフローテンプレート、CLI E2E スクリプトについては references/*.md を参照します。

編集前のリポジトリ同期（必須）

既存のリポジトリでファイルを作成／更新／削除する前に、現在のブランチをリモートと同期します。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

作業ツリーがクリーンでない場合は、まずスタッシュし、同期してから復元します。

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

origin がない場合、pull が利用できない場合、または rebase／スタッシュで競合が発生した場合は、作業を中断し、続行する前にユーザーに確認します。

安全策

このスキルは他者のリポジトリに設定を書き込み、git フックをインストールします。以下をすべて守ってください。

• 既存の .pre-commit-config.yaml や .github/workflows/*.yml を上書きしてはいけません。 対象ファイルが存在する場合は、次の手順でマージします。
  1. ファイルを <file>.bak にコピーします。
  2. マージ後の内容を準備します。ユーザー定義のフック、ジョブ、固定された rev: の値は保持します。
  3. <file>.bak とマージ後の内容の差分をユーザーに提示します。
  4. ユーザーが承認した場合は、マージ後のファイルを書き込みます。拒否された場合は、元のファイルを変更せず、マージが拒否されたことを記録します。
  5. 書き込み後の結果をユーザーが承認するまで、<file>.bak を保持します。
• 新規ファイルは、書き込む前に必ずすべて提示します。 新しい .pre-commit-config.yaml やワークフローは差分として提示してください。ユーザーが確認していないファイルを書き込んではいけません。
• フックをインストールする前に、検証とドライランを行います。 ステップ2では pre-commit install の前に pre-commit validate-config と pre-commit run --all-files を実行し、コミットを妨げることなく問題を表面化させます。
• インストール前に、既存の git フックがあるか確認します。 pre-commit install は、既存の別フックを .git/hooks/<hook>.legacy に移動して移行モードで実行することで、そのフックを保持します。そのフックを黙って削除する -f／--overwrite は決して指定しないでください。ユーザーが既存の別フックの削除を希望する場合は、事前に明示的な確認を得てください。
• ユーザーの代わりに git commit --no-verify や git push --no-verify を実行してはいけません。 フックの失敗は報告すべき問題であり、回避すべき障害ではありません。
• 失敗を表面化させ、決して隠してはいけません。 実行を成功扱いにするために、フック ID を SKIP に追加したり、Lint ルールを緩和したり、カバレッジしきい値を下げたりしてはいけません。失敗を報告し、判断はユーザーに委ねます。
• スタックを検出できない場合、pre-commit がない場合、または origin がない場合は、推測せずに中断します。 それぞれのケースについては「エッジケース」を参照してください。

ワークフロー

1. プロジェクトを分析する

プロジェクトの特性を検出します。

# Check for package files and configs
ls -la package.json pyproject.toml Cargo.toml go.mod pom.xml build.gradle *.csproj 2>/dev/null
ls -la .eslintrc* .prettierrc* tsconfig.json mypy.ini setup.cfg ruff.toml 2>/dev/null
ls -la .pre-commit-config.yaml .github/workflows/*.yml 2>/dev/null

以下を特定します。

• 言語：JS/TS、Python、Go、Rust、Java、C# など
• フレームワーク：React、Next.js、Django、FastAPI など
• ビルドシステム：npm、yarn、pnpm、pip、poetry、cargo、go、maven、gradle
• 既存のツール：すでに設定されているリンター、フォーマッター、型チェッカー
• CLI ツールかどうか — 該当する場合は、すべてのコマンド／サブコマンドを列挙し（README、--help、click／argparse／cobra のソースを確認）、E2E テストスイートを構築します。

パッケージマニフェストが見つからない場合は、ステップ 2 に進む前に、言語とビルドシステムをユーザーに確認してください。言語、ビルドシステム、既存のツール、既存の設定ファイル、CLI かどうか（コマンド一覧を含む）を記録した時点で、ステップ 1 は完了です。

2. Pre-commit フックを設定する（ローカルでのカバレッジを最大化）

pre-commit がない場合は、インストールコマンドを提示して停止します。エッジケースを参照してください。自動ではインストールしないでください。

pip install pre-commit  # or brew install pre-commit

pre-commit が利用可能な場合は、検出したスタックに合わせて .pre-commit-config.yaml を作成します。ファイルが存在する場合は、安全策に沿ったマージ手順を使用します。言語固有の設定については、references/precommit-configs.mdを参照してください。

pre-commit ステージ — すべてのコミットで実行し、変更されたファイルに対して 10 秒以内に完了：

• フォーマットチェック（Prettier、Black/Ruff、gofmt、rustfmt）
• リント（ESLint、Ruff、golangci-lint、Clippy）
• 型チェック（tsc、mypy）
• オフラインで実行できるセキュリティスキャン（Bandit、cargo-audit、gosec、detect-secrets）
• 高速なユニットテスト
• ビルド／コンパイルの検証（インポートエラーやコンパイル失敗を早期に検出）

pre-push ステージ — すべての git push で実行し、60 秒以内に完了：

• テストスイート全体（ユニット＋統合）
• すべての CLI コマンドのエンドツーエンドテスト（以下を参照）
• カバレッジしきい値の適用
• 時間のかかるリンター（golangci-lint の全ルールセット）

GitHub Actions のみ — ノート PC では実行できないもの：

• マトリックスによるバージョンテスト（複数の Node/Python/Go バージョン）
• シークレットを使ったスキャン（Snyk、トークンが必要な SAST ツール）
• デプロイ／リリースのワークフロー
• 外部サービスへのカバレッジのアップロード
• クリーンな VM が必要な、不安定なテストや環境の影響を受けやすいテスト

最新のステージ名を使用してください。 pre-commit 3.2 では commit が pre-commit に、push が pre-push に変更されました。旧名は 4.x で非推奨の警告を出し、将来的に削除される予定です。必ず新しい名前を使用し、旧名を使っている既存の設定には pre-commit migrate-config を実行してください。

CLI のエンドツーエンドテスト

プロジェクトが CLI ツールの場合は、すべてのコマンド／サブコマンドを実行して、CLI がコンパイルできるだけでなく、エンドツーエンドで動作することを検証する scripts/e2e_test.sh を作成します。これを pre-push ステージの pre-commit に組み込みます。

コマンドの検出パターン、スクリプトのテンプレート、pre-commit フックのスニペットについては、references/cli-e2e.mdを参照してください。

設定を検証してドライランを実行してから、次の順序でフックをインストールします。

1. pre-commit validate-config .pre-commit-config.yaml を実行します。ゼロ以外の終了コードが返された場合は、エラーを報告し、フックをインストールする前に停止してください。
2. pre-commit run --all-files を実行します。このドライランでは、インストールせずにコミットステージのフックが実行されます。失敗したフック ID をそれぞれ検出事項として記録してください。
3. git rev-parse --git-path hooks が出力するディレクトリ（常に .git/hooks とは限りません）で pre-commit と pre-push を確認します。いずれかが存在し、File generated by pre-commit を含まない場合は、<hook>.legacy に移動することをユーザーに伝えてください。
4. pre-commit install を実行します。
5. pre-commit install --hook-type pre-push を実行します。pre-commit install だけでは pre-push フックはインストールされません。

git commit --no-verify と git push --no-verify はすべてのフックをスキップするため、ローカルでそれを防ぐ方法はありません。これらのゲートを強制するのはステップ 3 の CI バイパスガードです。CI を簡素化する際も、このガードを削除しないでください。

3. GitHub Actions ワークフローを作成する（軽量な CI）

ワークフローが存在しない場合は、.github/workflows/ci.yml を作成します。すでに存在する場合は、Safety Rails のマージ手順を使用し、フックと重複する既存の各ステップを、削除候補として差分に記載します。ユーザーの確認後にのみ、ステップを削除してください。CI は最小限に保ちます。ローカルで実行される処理はすでにフックで実行済みなので、CI ではルーティング表の第 3 レーンと 1 つのガードをカバーします。ワークフローテンプレートについては、references/github-actions.md を参照してください。

CI で実行するのは、次の 4 種類だけです。

1. バイパスガード — プルリクエストの差分に範囲を絞って両方のフックステージを再実行するため、数分ではなく数秒で完了します。これは pre-commit と意図的に重複する唯一の処理で、--no-verify によってローカルのゲートが任意になってしまうのを防ぐためにあります。
2. バージョンマトリックス — 複数のランナーが本当に必要となる唯一のレーンです。
3. シークレットに依存する処理 — ノート PC に保持すべきではないトークンを必要とするスキャンやアップロードです。
4. デプロイ／リリース — デフォルトブランチへのマージ時に実行します。

バイパスガードの全体は次のとおりです。

  hooks:
    name: Verify hooks were not bypassed
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      # ... set up the project toolchain and Python here ...
      - name: Run both hook stages over the PR diff
        run: |
          pip install pre-commit
          base="${{ github.event.pull_request.base.sha }}"
          pre-commit run --from-ref "$base" --to-ref HEAD
          pre-commit run --hook-stage pre-push --from-ref "$base" --to-ref HEAD

次の 4 つの詳細は不可欠です。どれか 1 つでも欠けると、ジョブは初回実行時に失敗します。

• 両方の pre-commit run 行。 最初の行で実行されるのはコミットステージのフックだけです。フルスイートと CLI の E2E テストは pre-push で実行されるため、2 行目がなければひそかにスキップされます。pre-commit/[email protected] にも同じ盲点があるため、CLI を直接呼び出してください。
• fetch-depth: 0。 actions/checkout は深さ 1 でクローンするため、ベース SHA がなく、--from-ref は不正なオブジェクトを参照して失敗します。
• if: github.event_name == 'pull_request'。 push イベントでは、ブランチへの初回プッシュ時の github.event.before はすべてゼロであり、強制プッシュ後は古い値になります。
• 同じジョブ内のプロジェクトのツールチェーン。 language: system が宣言されたフックは、npm、mypy、go、cargo をシェルから呼び出します。

マトリックスは頻繁に実行される経路から外し、すべてのプルリクエストのコミットではなく、デフォルトブランチへの push またはリリースタグを条件にします。プッシュごとに 3 バージョンのマトリックスを実行すると、フックがすでにローカルで提供したシグナルに対して、コストが 3 倍になります。

4. パイプラインを検証する

1. pre-commit run --all-files を実行します。期待値：終了コード 0。
2. pre-commit run --all-files --hook-stage pre-push を実行します。期待値：終了コード 0。最初のコマンドでは、プッシュステージのフック（フルスイート、E2E）は実行されません。
3. プロジェクトが CLI ツールの場合は、bash scripts/e2e_test.sh を実行します。期待値：終了コード 0。
4. コマンドが 0 以外のコードで終了した場合は、失敗したフック ID とその出力を所見として記録します。合格させるために設定を編集したり、SKIP を追加したり、しきい値を下げたりしないでください。

各コマンドの終了コードが記録されていれば、ステップ 4 は完了です。ステップ 3 のワークフローはここでは実行しません。次のプルリクエストで、GitHub 上で初めて実行されます。

最終レポートを作成する

最後のステップ完了レポートの後に、references/final-report.md の最終レポートを出力します。最初に Result:（COMPLETE、PARTIAL — reason、または BLOCKED — reason）、次に Evidence:（実行したコマンドのみ。終了コードを記載）、Uncertainty:（未実行の CI ワークフローを必ず記載）、最後に Decision:（保留中の承認、または No approval needed.）を記載します。監査のみを実行した場合も、同じレポートを使用します。

言語別のツール選択

言語	フォーマッター	リンター	型チェック	セキュリティ	テスト
JS/TS	Prettier	ESLint	tsc	npm audit	Jest/Vitest
Python	Ruff/Black	Ruff	mypy	Bandit + detect-secrets	pytest
Go	gofmt	golangci-lint	built-in	gosec	go test
Rust	rustfmt	Clippy	built-in	cargo-audit	cargo test
Java	google-java-format	Checkstyle	-	SpotBugs	mvn test

これらがどのレーンに属するかは、上記のチェックルーティング表で定められています。ここでチェックを別の方法で分割しないでください。

期待される出力

スキルを実行すると、リポジトリには次のものが含まれます。

1. .pre-commit-config.yaml — pre-commit ステージではフォーマット、リンティング、型チェック、高速なユニットテストを実行し、pre-push ステージではテストスイート全体、カバレッジしきい値、E2E テストを実行します。
2. .github/workflows/ci.yml — ステップ 3 の 4 つの役割のみを担う CI：差分対象を限定したバイパスガード、バージョンマトリックス、シークレットに依存する処理、デプロイ。フックと重複する、独立したリンティング、フォーマット、型チェック、テストのステップは含めません。
3. scripts/e2e_test.sh（CLI プロジェクトのみ）— すべての CLI コマンド／サブコマンドを実行する実行可能スクリプトです。
4. references/final-report.md の形式に沿った最終レポート。

Python プロジェクト向け .pre-commit-config.yaml のスニペット例：

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.4
    hooks:
      - id: ruff
        stages: [pre-commit]
      - id: ruff-format
        stages: [pre-commit]
  - repo: local
    hooks:
      - id: mypy
        name: mypy type check
        entry: mypy src/
        language: system
        stages: [pre-commit]
      - id: pytest-fast
        name: fast unit tests
        entry: pytest tests/unit -x -q
        language: system
        stages: [pre-commit]
      - id: pytest-full
        name: full test suite
        entry: pytest --cov=src --cov-report=xml
        language: system
        stages: [pre-push]

受け入れ基準

以下のすべてを満たすと、実行は合格です。

• .pre-commit-config.yaml がリポジトリのルートにあり、検出された主要言語向けのフック（フォーマッター、リンター、または型チェッカー）が少なくとも 1 つ記載されています。
• 各チェックは Check Routing Table のレーンのいずれか 1 つだけに属しています。.pre-commit-config.yaml のフック id がバイパスガード以外のワークフローの run: ステップに登場せず、ノート PC 上で実行できるチェックが CI 専用になっていません。
• フックの stages: では最新の名前（pre-commit、pre-push、manual）を使用し、生成される設定に非推奨の commit または push を含めません。
• 両方の種類のフックがインストールされています：pre-commit install および pre-commit install --hook-type pre-push。
• .github/workflows/*.yml が少なくとも 1 つあり、ステップ 3 の 4 つの CI の役割のみを担っています。
• CI で pre-commit と重複するのはバイパスガードのみで、そのガードは差分対象を限定し（--from-ref／--to-ref）、両方のステージを実行します。
• pre-commit run --all-files と pre-commit run --all-files --hook-stage pre-push の両方が成功するか、失敗が自動的に抑制されず、ユーザーに明示されます。
• CLI プロジェクトでは、言語別のリファレンスファイルに従って、E2E スクリプトが pre-push ステージに接続されています。
• 最終レポートは references/final-report.md にある 4 つの読者チェックを満たしています：結果が 1 行目に記載されていること、検証済みの事実と仮定が区別されていること、各主張にコマンドまたはファイルが明記されていること、次の判断が明示されていること。ユーザーからのフィードバックがない場合、人間が理解したことは未確認のままです。

エッジケース

• パッケージマネージャーが検出されない：フックを生成する前に、言語／ビルドシステムをユーザーに確認します。黙って推測してはいけません。
• Pre-commit がインストールされていない：インストールコマンド（pip install pre-commit または brew install pre-commit）を表示して停止します。自動インストールしたり、設定ファイルを生成したりしてはいけません。
• 既存の .pre-commit-config.yaml：上書きするのではなく、既存のファイルに新しいフックをマージします。ユーザー定義のフックと固定された rev を保持します。
• 複数の言語を使うモノレポ：言語ごとのフックセクションを含む 1 つの設定を生成し、files: のパスフィルターを使って、フックが関連するサブディレクトリでのみ実行されるようにします。ローカルの language: system エントリーもパッケージディレクトリを対象にする必要があります（npm --prefix frontend、pytest backend/tests）。files: はフックを起動するファイルをフィルタリングするだけで、cwd は変更しません。
• origin リモートがない：リポジトリ同期なしのローカルのみの設定で問題ないかをユーザーに確認して停止します。自動的に続行してはいけません。
• テストに 60 秒を超える：次のレーンに降格します。pre-commit から pre-push、または pre-push から CI に移します。その理由をフックのコメントに記録し、次に読む人が推測ではなく計測結果に基づく判断だと分かるようにします。
• 非推奨のステージ名を使うレガシー設定：新しいフックをマージする前に pre-commit migrate-config を実行し、ファイルが一部だけ移行された状態にならないようにします。
• チームが --no-verify でフックを回避する：ローカルのゲートではこれを阻止できません。CI のバイパスガードを維持し、フックを増やすのではなく、バイパス率を報告します。
• Windows 専用のリポジトリ：PowerShell に対応したフックエントリーに置き換え、Unix 固有のコマンドがあれば明示します。

ステップ完了レポート

各主要ステップの完了後、次の形式でステータスレポートを出力します。

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

チェック名は、そのステップで実際に検証する内容に合わせてください。合格には √、不合格には × を使用し、簡単な補足を加える場合は — を使用します。「Criteria」行には、達成した受け入れ基準の数をまとめます。「Result」行には、全体的な判定を記載します。

フェーズごとのスキル固有チェック

フェーズ：プロジェクト分析 — チェック項目：Project detection、Existing tooling scan、CLI detection、Command enumeration

フェーズ：Pre-commit 設定 — チェック項目：Pre-commit setup、Commit-stage hooks installed、Push-stage hooks installed、Modern stage names used、E2E script created (if CLI)

フェーズ：GitHub Actions 設定 — チェック項目：GitHub Actions config、CI limited to the four responsibilities、Bypass guard runs both stages、Matrix off the per-commit path

フェーズ：パイプライン検証 — チェック項目：Commit-stage hooks pass、Push-stage hooks pass、E2E tests pass (if CLI)、No check duplicated across lanes

リソース

• references/precommit-configs.md — 言語別の pre-commit 設定、pre-push テスト、E2E フック
• references/github-actions.md — GitHub Actions テンプレート：バイパスガード、マトリックス、デプロイ
• references/cli-e2e.md — CLI コマンドの検出、E2E スクリプトのテンプレート、その pre-push フック
• references/final-report.md — 最終レポートの各項目、ステータスのルール、例、読み手向けチェック