git-workflow

Git ワークフロー

ブランチ戦略、Conventional Commits、CI/CD の自動化、リポジトリの整理、Git の内部構造について説明します。GitHub CLI の使用方法は別の github-cli スキルで扱います。このスキルでは、Git のワークフローパターンと CI/CD の設定に焦点を当てます。

クイックリファレンス

領域	主な実践事項
ブランチ	トランクベース開発と短命な機能ブランチ
コミット	命令形の Conventional Commits
履歴	リベースで履歴を直線化し、不要なコミットはスカッシュ
PR	小規模な変更を積み重ね、巨大な PR は避ける
メインブランチ	常にデプロイ可能な状態にする。メインブランチの破損は緊急事態
CI/CD	再利用可能なワークフローを用いたモジュール式の GitHub Actions
マージ	マージ前に CI の成功とレビューを必須にする
バージョン管理	Semantic Release または Changesets を使用する（手動では行わない）
ブランチ	存続期間は最大 48 時間。古いブランチやマージ済みブランチは自動削除
シークレット	パイプラインでは OIDC Connect を使用し、トークンをハードコードしない
署名	作者を検証できるよう、SSH または GPG キーでコミットに署名する

ブランチの命名

種類	用途	例
feat	新機能	feat/add-user-auth
fix	バグ修正	fix/login-redirect
chore	メンテナンス	chore/update-deps
docs	ドキュメント	docs/api-reference
refactor	コードの再構成	refactor/auth-module

Conventional Commit の種類

種類	目的	バージョンの更新
feat	新機能	マイナー
fix	バグ修正	パッチ
docs	ドキュメントのみ	なし
style	書式の変更。ロジックの変更なし	なし
refactor	修正でも機能追加でもない変更	なし
perf	パフォーマンスの改善	パッチ
test	テストの追加または修正	なし
build	ビルドシステムまたは外部依存関係	なし
ci	CI 設定の変更	なし
chore	ツール、メンテナンス、ソース以外の変更	なし
revert	以前のコミットの取り消し	変更内容による

破壊的変更の場合は、種類またはスコープの後に ! を付けます（メジャーバージョンが更新されます）。

マージ前のチェック

すべての PR では、マージ前に以下が必要です。

• リント
• 型チェック
• テスト
• セキュリティスキャン
• レビュー承認（人間または自動）

パイプラインが成功した場合、リスクの低い PR では自動マージを許容できます。

トラブルシューティング

問題	解決策
長期間存続するブランチでのマージ競合	頻繁にメインへリベースします。48 時間を超える場合は、残りの作業を新しいブランチに分割します
メインブランチの破損	緊急事態として扱い、問題を引き起こしたコミットを取り消してから、ブランチで修正を進めます
コミットの紛失またはデータの復旧	git reflog とオブジェクトの検査（git cat-file、git fsck）を使用します
CI パイプラインの失敗	再利用可能なワークフローのバージョンを確認し、OIDC の権限を検証します
リベース後の積み重ねた PR の競合	ベースからチェーン全体を積み直します。Graphite では gt restack により自動処理されます
大きなファイルを誤ってコミットした	git filter-repo を使用して履歴から削除します（git filter-branch は使用しません）

よくある間違い

間違い	正しいパターン
48 時間を超えてフィーチャーブランチを維持する	毎日マージまたはリベースし、大きな作業は積み重ね型 PR に分割する
ブランチ保護なしで main に直接コミットする	CI とレビューを必須とするブランチ保護ルールを有効にする
履歴を煩雑にするマージコミットを使用する	履歴を直線的に保つため、リベースしてスカッシュする
GitHub Actions ワークフローにトークンをハードコードする	CI/CD パイプラインでの認証に OIDC Connect を使用する
単一ファイルにモノリシックな CI ワークフローを作成する	再利用可能なワークフローとコンポジットアクションに分割する
コミットメッセージに Fix bug を使う	fix(scope): correct bug description（規約に準拠）
feat: Added feature（過去形）	feat: add feature（命令形、小文字）
履歴の書き換えに git filter-branch を使う	git filter-repo を使う（より高速で安全、公式に推奨）
main に直接プッシュする	先にフィーチャーブランチを作成する
共有リポジトリで署名なしのコミットを使う	SSH または GPG キーでコミット署名を設定する

委任

• リポジトリのブランチ管理状況と古いブランチを監査する：Explore エージェントを使って、ブランチの経過期間とマージ状況を一覧表示し、分類します
• 再利用可能なワークフローを使って CI/CD パイプラインを設定する：Task エージェントを使って、モジュール化された GitHub Actions の設定を作成します
• 新しいプロジェクトのブランチ戦略を設計する：Plan エージェントを使って、チームのニーズに基づきトランクベース開発と Git Flow を評価します

参考資料

• branching-strategies.md -- Git Flow、GitHub Flow、GitLab Flow、One-Flow の比較と選択基準
• trunk-based-development.md -- 基本原則、ワークフローの手順、フィーチャーフラグ、アンチパターン
• stacked-changes.md -- 積み重ね型 PR の概念、手動での積み重ね、Graphite による自動化、ベストプラクティス
• conventional-commits.md -- コミット形式、タイプ、スコープ、破壊的変更、ワークフロー全体
• github-actions.md -- 再利用可能なワークフロー、マトリックステスト、デプロイ環境、セキュリティ
• git-internals.md -- オブジェクトモデル、SHA ハッシュ、インデックス、参照、パックファイル、ガベージコレクション
• automation-scripts.md -- ブランチの整理、セマンティックリリース、セキュリティスキャン、積み重ね型 PR 用ヘルパー
• issue-templates.md -- バグ報告、機能リクエスト、タスク、最小限の issue テンプレート
• advanced-operations.md -- コミット署名、対話型リベース、ワークツリー、二分探索、reflog による復旧、--force-with-lease