managing-git-workflows

Git ワークフロー

チームでの共同作業、コード品質、自動リリースのために、体系的な Git ワークフローを実装します。このスキルでは、ブランチ戦略、Conventional Commits の形式、Git フック、モノレポの管理パターンを扱います。

このスキルを使うタイミング

次の場合にこのスキルを使います：

• 新しいプロジェクトやチームのブランチ戦略を選ぶとき
• 一貫したコミットメッセージの形式を導入するとき
• リント、テスト、検証のために Git フックを設定するとき
• 複数のプロジェクトを含むモノレポを管理するとき
• コードレビューのワークフローを確立するとき
• バージョン管理とリリースを自動化するとき

クイック判断：どのブランチ戦略を選ぶか？

トランクベース開発

チームに強力な CI/CD 自動化と包括的なテストカバレッジ（80％以上）があり、頻繁に（1日1回以上）デプロイする場合に使います。短命のブランチは1日以内にマージします。未完成の機能にはフィーチャーフラグが必要です。

最適な対象： 成熟した DevOps プラクティスを持つ、高速で開発を進めるチーム（Google、Facebook、Netflix）

GitHub Flow

継続的デプロイを行うウェブアプリケーションに使います。メインブランチは常に本番環境を表します。小規模から中規模（開発者2～20人）のチーム向けの、シンプルな PR ベースのワークフローです。

最適な対象： スタートアップ、SaaS 製品、オープンソースプロジェクト

GitFlow

複数の本番バージョンを同時にサポートする場合、正式な QA サイクルが必要な場合、または定期リリース（月次、四半期ごと）に従う場合に使います。複雑ですが、体系的に管理できます。

最適な対象： エンタープライズソフトウェア、App Store でリリースするモバイルアプリ、オンプレミス製品

ブランチパターンの詳細と例については、references/branching-strategies.md を参照してください。

Conventional Commits

自動バージョン管理と変更履歴の生成に向けて、コミットメッセージを構成します：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

一般的なタイプ：

• feat - 新機能（MINOR バージョンの更新：0.1.0）
• fix - バグ修正（PATCH バージョンの更新：0.0.1）
• docs - ドキュメントのみ
• refactor - 機能を変更しないコードの再構成
• test - テストの追加または更新
• chore - 保守作業

破壊的変更：

• タイプの後に ! を追加します：feat!: または fix!:
• フッターに BREAKING CHANGE: を追加します
• MAJOR バージョンの更新になります（1.0.0）

例：

git commit -m "feat(auth): add JWT token validation"
git commit -m "fix: resolve race condition in user login"
git commit -m "feat!: redesign authentication API

BREAKING CHANGE: Auth endpoints now require API version header"

完全な仕様とツールの設定については、references/conventional-commits.md を参照してください。

品質ゲートのための Git フック

ワークフローの重要なタイミングで、コード品質チェックを自動化します：

pre-commit - コミット作成前に実行

• リント（ESLint、Prettier）
• フォーマットのチェック
• 簡易テスト

commit-msg - コミットメッセージの形式を検証

• Conventional Commits の形式を徹底
• メッセージの長さを確認

pre-push - リモートへのプッシュ前に実行

• テストスイート全体
• 保護されたブランチへの強制プッシュを防止

Husky を使ったクイックセットアップ：

npm install --save-dev husky lint-staged @commitlint/cli @commitlint/config-conventional
npx husky init
npx husky add .husky/pre-commit "npx lint-staged"
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

フックの完全な設定と例については、references/git-hooks-guide.md を参照してください。

モノレポの管理

ビルドツールの選択

Nx - TypeScript／JavaScript のモノレポに最適

• 依存関係グラフの分析
• 影響範囲に応じたコマンド（変更されたプロジェクトのみを再ビルド）
• 分散キャッシュ

Turborepo - Next.js／React アプリケーションに最適

• 高速なインクリメンタルビルド
• リモートキャッシュ
• シンプルな設定

Sparse Checkout - 完全なクローンが不要な大規模リポジトリ向け

git sparse-checkout init --cone
git sparse-checkout set apps/web libs/ui-components

コードのオーナーシップ

.github/CODEOWNERS を使ってオーナーシップを定義します：

# Default owners
* @org/engineering

# Apps ownership
/apps/web/ @org/web-team
/apps/mobile/ @org/mobile-team

# Security-critical
/libs/auth/ @org/security-team @org/principal-engineers

モノレポのパターンの詳細については、references/monorepo-patterns.md を参照してください。

マージとリベースの比較

マージコミット

完全な履歴を保持することが重要な場合に使います：

git checkout main
git merge feature-branch

使用する状況： フィーチャーブランチで複数の開発者が作業しており、統合ポイントを確認したい場合

スカッシュしてマージ

クリーンで直線的な履歴にする場合に使います：

git checkout main
git merge --squash feature-branch
git commit -m "feat: add user authentication"

使用する状況： フィーチャーに WIP コミットが多数あり、メインブランチの履歴を整理したい場合

リベース

マージコミットを作成せずに直線的な履歴にする場合に使います：

git checkout feature-branch
git rebase main

使用する状況： フィーチャーブランチを更新する場合、一人で作業する場合、PR の前に履歴を整理する場合

⚠️ リベースしないでください： 公開ブランチ（main、develop）、またはすでにプッシュされ、他の人が利用しているコミット

コードレビューワークフロー

プルリクエストテンプレート

.github/PULL_REQUEST_TEMPLATE.md を作成します：

## Description


## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed code
- [ ] Added tests
- [ ] Updated documentation
- [ ] Tests pass locally

ブランチ保護ルール

リポジトリの設定で品質ゲートを適用します。

• プルリクエストレビューを必須にする（承認 2 件以上）
• ステータスチェックを必須にする（ビルド、テスト、リンティング）
• マージ前にブランチを最新の状態にすることを必須にする
• 強制プッシュと削除を制限する

コードレビューの設定全般については、references/code-review-workflows.md を参照してください。

ブランチの命名規則

明確さを保つため、一貫した命名を使用します。

• feature/user-authentication - 新機能
• bugfix/login-error - バグ修正
• hotfix/critical-security-issue - 本番環境の緊急修正
• docs/api-documentation - ドキュメントの変更
• refactor/database-layer - コードのリファクタリング

Git フックでブランチ名を検証します（scripts/check-branch-name.sh を参照）。

高度なテクニック

ホットフィックスのためのチェリーピック

特定のコミットを別のブランチに適用します。

git checkout main
git commit -m "fix: resolve critical security issue"
# Commit hash: a1b2c3d

git checkout release/1.5
git cherry-pick a1b2c3d

大容量ファイル向けの Git LFS

大容量ファイルをコードとは別に追跡します。

git lfs install
git lfs track "*.psd"
git lfs track "*.mp4"
git add .gitattributes

リリースタグ付け

本番リリースをマークします。

git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

インタラクティブリベース

PR の前にコミット履歴を整理します。

git rebase -i HEAD~3
# Squash WIP commits, reword messages, reorder commits

詳しい例については、examples/ ディレクトリを参照してください。

リリースワークフローの自動化

Conventional Commits と CI/CD を組み合わせて、バージョン管理を自動化します。

1. コミット - Conventional Commits 形式に従います
2. 分析 - Semantic Release がコミットの種類を分析します
3. バージョン - MAJOR.MINOR.PATCH の更新幅を決定します
4. 変更履歴 - コミットから自動生成します
5. タグ - Git タグを作成します
6. 公開 - npm、GitHub リリースなどにデプロイします

設定全般については、examples/semantic-release-setup/ を参照してください。

ツールの推奨

Git フック：

• Husky - フック管理を簡素化します（最も広く利用されています）
• lint-staged - ステージング済みファイルに対してのみリンターを実行します（パフォーマンス向上）

コミットの検証：

• Commitlint - Conventional Commits の形式を適用します
• Semantic Release - バージョン管理を自動化します

モノレポのビルド：

• Nx - TypeScript/JavaScript 向け（Google、AWS が使用）
• Turborepo - Next.js/React 向け（Vercel）

大容量ファイル：

• Git LFS - 大容量のバイナリファイルを保存します

すべてのツールは、Context7 による検証済みで、高い信頼スコアを得ています（2025 年 12 月）。

他のスキルとの連携

building-ci-pipelines - Git ワークフローが CI/CD パイプラインを起動し、ブランチ保護が CI チェックを適用します

writing-github-actions - GitHub Actions がワークフローのステップ（リリース、PR チェック）を自動化します

infrastructure-as-code - IaC リポジトリには構造化されたワークフローが必要です。GitOps では Git を信頼できる情報源として使用します

testing-strategies - Git フックがテスト要件を適用し、プッシュ前にテストスイートを実行します

security-hardening - Git フックがシークレットの登録を防ぎ、署名付きコミットが身元を検証し、CODEOWNERS がセキュリティレビューを適用します

クイックリファレンス

トランクベース開発ワークフロー

git checkout -b feature/add-login main
git add .
git commit -m "feat: add login form component"
git rebase origin/main  # Stay up to date
git push origin feature/add-login
# PR → merge → delete branch (within 24 hours)

GitHub Flow ワークフロー

git checkout -b feature/user-auth main
git commit -m "feat: add JWT authentication"
git commit -m "test: add auth tests"
git push origin feature/user-auth
# Open PR → review → merge → deploy → delete branch

GitFlow ワークフロー

# Feature
git checkout -b feature/user-profile develop
git commit -m "feat: add user profile"
git checkout develop
git merge --no-ff feature/user-profile

# Release
git checkout -b release/1.1.0 develop
git checkout main
git merge --no-ff release/1.1.0
git tag -a v1.1.0 -m "Release 1.1.0"

# Hotfix
git checkout -b hotfix/critical-bug main
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v1.1.1 -m "Hotfix 1.1.1"

検証スクリプト

自動チェックを実行します。

• scripts/validate-commit-msg.sh - コミットメッセージの形式を検証します
• scripts/check-branch-name.sh - ブランチの命名規則を検証します
• scripts/setup-hooks.sh - フックのインストールを自動化します

検証には、スクリプトを直接実行してください（トークン不要）。