- 概要
本ドキュメントはチーム向けの統一されたGitブランチ管理規約を確立することを目的とします。ブランチ作成、開発協調、コード統合、バージョンデプロイといった主要プロセスをカバーします。標準化されたプロセスと規約により、協働コストを削減し、コード品質を向上させ、リリースの安全性を確保します。
1.1 適用範囲
- すべてのバックエンドサービスプロジェクト
- すべてのフロントエンドプロジェクト
- 日常開発、緊急修正（Hotfix）、バージョンイテレーションなどを含む
1.2 核心原則
| 原則 | 説明 |
|---|---|
| **メインブランチは常にリリース可能** | main / RELEASE ブランチは安定し、デプロイ可能な状態を維持する必要があります |
| **ブランチの分離** | 異なる要件/機能は独立したブランチで開発し、相互に影響を与えないようにします |
| **上向き統合、逆方向の汚染禁止** | main → feature → private 方向での同期のみ許可し、test/pre を開発ブランチにマージすることは厳禁です |
| **少量頻回** | 頻繁なコミットと統合を行い、広範なコード競合を回避します |
| **レビュー後に統合** | メインブランチに統合されるすべてのコードはコードレビューを経る必要があります |
- ブランチモデル
2.1 ブランチ体系概要
main / RELEASE ← 本番環境（このブランチからのみデプロイ可能）
│
├── pre-production / pre-branch ← 準本番環境
│
├── test / testing ← テスト環境
│
├── feature/xxx ← 機能開発メインブランチ（mainから作成）
│ │
│ ├── personal/xxx-A ← 個人開発ブランチ（featureから作成）
│ └── personal/xxx-B
│
└── hotfix/xxx ← 緊急修正ブランチ（mainから作成）
2.2 各ブランチの役割
| ブランチタイプ | 説明 | ソース | ライフサイクル |
|---|---|---|---|
main / RELEASE |
本番環境コード、安定したリリース可能な状態を維持 | — | 永続 |
pre-production / pre-branch |
準本番検証環境 | — | 永続 |
test / testing |
テスト環境 | — | 永続 |
feature/xxx |
機能開発メインブランチ、1つの完全な要件を担当 | mainから作成 |
要件がリリース後に削除 |
personal/xxx |
個人開発ブランチ、日常のコーディングはここで行う | featureから作成 |
統合後に削除 |
hotfix/xxx |
本番環境の緊急問題修正 | mainから作成 |
修正がリリース後に削除 |
GitLabではmain/pre-production/test/featureブランチに保護が設定され、直接コードのプッシュは禁止されています。コード統合はMR（マージリクエスト）のみ許可されます。 testブランチは、プロジェクトのテスト環境が他のプロジェクトに影響を与えない場合、保護を解除し、直接コードをプッシュできます。
- ブランチ命名規約
3.1 命名形式
<タイプ>/<簡潔な説明>
3.2 命名ルール
| ブランチタイプ | 形式 | 例 |
|---|---|---|
| 機能開発メインブランチ | feature/<機能説明> |
feature/user-management |
| 個人開発ブランチ | personal/<日付>-<機能> または personal/<機能説明> |
personal/20260415-user-login、personal/user-list |
| 緊急修正ブランチ | hotfix/<問題説明> |
hotfix/login-bug |
3.3 命名要件
- 小文字とハイフン（kebab-case）を使用する（例:
feature/order-export） - 名称は機能や問題を明確に説明し、可読性を優先する
- 特殊文字、スペース、中国語の使用は禁止
- 開発協調プロセス
4.1 単人開発プロセス
単一の開発者が独立して要件を完了する場合に適用されます。
1. mainからfeatureブランチを作成
2. featureからpersonalブランチを作成
3. personalブランチで開発とコミットを行う
4. MRを使用してpersonalをfeatureに統合
5. featureブランチでグレースケールリリースとテスト検証
6. 検証が通過したら、MRを使用してfeatureをmainに統合
# ステップ1: 機能ブランチの作成
git checkout main
git pull origin main
git checkout -b feature/user-management
# ステップ2: 個人ブランチの作成
git checkout feature/user-management
git checkout -b personal/user-list
# ステップ3: 開発とコミット
git add .
git commit -m "feat: ユーザーリスト機能の追加"
# ステップ4: プッシュしてGitLabでfeatureブランチにMR提出
git push origin personal/user-list
4.2 複数人協調開発プロセス
複数の開発者が同じ要件/モジュールを協調して完了する場合に適用されます。
1. 責任者がmainからfeatureブランチを作成
2. 各開発者がfeatureからそれぞれのpersonalブランチを作成
3. 個々がpersonalブランチで並列開発
4. 機能の一部が完成するたびにfeatureにMRで統合（少量頻回）
5. featureブランチでグレースケールリリースとテスト検証
6. 機能が完了したら、feature → mainに統合
# 責任者の機能ブランチ作成
git checkout main && git pull origin main
git checkout -b feature/user-management
# 開発者A
git checkout feature/user-management && git pull
git checkout -b personal/user-list
# 開発者B
git checkout feature/user-management && git pull
git checkout -b personal/user-form
4.3 緊急修正プロセス（Hotfix）
本番環境の緊急問題修正に適用されます。
# 1. mainからhotfixブランチを作成
git checkout main
git pull origin main
git checkout -b hotfix/login-bug
# 2. 問題を修正してコミット
git add .
git commit -m "fix: ログイン検証ロジックの誤りを修正"
# 3. プッシュしてGitLabでmainにMR提出
git push origin hotfix/login-bug
修正プロセスの重要点：
- hotfixブランチはmainから作成する必要があります
- 修正完了後はグレースケールリリースし、テスト検証用のグレースケールリンクを提供します
- 検証が通過したらMRでmainに統合します
- 統合後はtest / pre-productionブランチに同期する必要があります
4.4 ブランチ統合方向（ルールライン）
許容される統合方向:
main → feature → personal （コード同期）
personal → feature → main （コード統合）
❌ 厳禁の操作:
test / pre-production → personal （開発ブランチの汚染）
test / pre-production → feature （機能ブランチの汚染）
personal → main （featureをスキップし、レビュー不足）
核心ルール：mainとfeatureブランチのみが個人開発ブランチに統合でき、その他のブランチは一律禁止です。
- コミット規約
Conventional Commits規約に従います。
5.1 コミット形式
<タイプ>: <サブジェクト>
<ボディ>（オプション）
5.2 タイプ
| タイプ | 説明 | 例 |
|---|---|---|
feat |
新機能の追加 | feat: ユーザーログイン機能の追加 |
fix |
問題の修正 | fix: ログインページの検証ロジックエラーを修正 |
refactor |
コードリファクタリング（機能変更なし） | refactor: 注文検索ロジックの最適化 |
docs |
ドキュメントの変更 | docs: APIインターフェースドキュメントの更新 |
style |
コードフォーマットの調整（ロジックに影響なし） | style: コードインデントのフォーマット |
test |
テストの追加または変更 | test: ユーザーモジュールの単体テスト追加 |
chore |
ビルド、依存関係などの雑多な変更 | chore: 依存パッケージバージョンの更新 |
build |
ビルドシステムまたはCI/CDの変更 | build: webpack設定の更新 |
perf |
パフォーマンスの最適化 | perf: リストクエリ応答速度の最適化 |
5.3 コミット要件
- 各コミットは1つの論理変更のみを含む
- サブジェクトは日本語または英語を使用可能だが、チーム内で統一する
- 意味のないコミット情報（
update、fix、testなど）は禁止 - ボディ部分ではリスト形式で具体的な変更内容を記述
例：
feat: ユーザー管理ページの追加
- ユーザーリスト表示の実装
- ユーザー検索機能の追加
- ユーザー削除操作の完了
- マージリクエスト（MR）規約
6.1 MRタイトル規約
MRタイトルにはタイプ接頭辞を含め、コミットタイプと一致させる必要があります：
feat: ユーザー管理機能の追加
fix: 注文金額計算エラーの修正
hotfix: 支払いコールバック例外の緊急修正
6.2 MR必須項目
| 項目 | 要件 |
|---|---|
| **タイトル** | タイプ接頭辞を含め、変更内容を明確に説明 |
| **レビュワー** | 対応するリーダーまたはモジュール責任者を指定 |
| **関連要件** | すべてのMRは対応する要件に関連付け、関連付けを正確にする |
| **説明** | 変更の背景、影響範囲、テスト方法を説明 |
6.3 MRレビュープロセス
MR提出 → コードスキャン（Sonar）→ コードレビュー → コメント解決 → レビュー通過 → 統合
- コードスキャン：MR提出後に自動でSonarスキャンがトリガーされ、スキャンが未通過の場合は統合禁止
- コードレビュー：レビューコメントを追加後、提出ボタンをクリックしてコメントを有効にする必要があります
- コメント解決：提出者はCRコメントを一つずつ解決し、Resolveをクリックしてマークします
- 統合タイミング：CR問題がすべて解決したら速やかに統合し、長期間放置しない
6.4 コード品質要件
| 指標 | 要件 |
|---|---|
| Code Smell | すべて解決する必要があり、さもなければ統計され報告されます |
| 単体テストカバレッジ | **60%**以上、AIによるテストケース生成の使用を推奨 |
| Sonarスキャン | 必須通過、スキャン失敗時は再試行またはGitLabサポートに連絡 |
6.5 MR注意事項
- バグ修正：テストチームから報告されたバグはtestブランチで直接修正せず、個人開発ブランチで修正後にtestに統合する必要があります
- 不要なMRの早期クローズ：統合しないMRは速やかにクローズし、同じコミットのMRが統合された際に自動統合されるのを防ぎます
- Rebase処理：MRでrebaseが必要と表示された場合、ターゲットブランチの最新コードをMRソースブランチ（例:
xxx-fortest）に統合し、個人開発ブランチには統合しないでください（汚染を防ぐため）
- コード統合戦略
7.1 featureブランチへの統合
- 日常開発では、機能の一部が完成するたびにfeatureブランチにMRで統合します
- 機能がすべて完成するまで待つ必要はありません—少量頻回、継続的統合
- テスト提出時のみfeatureブランチがグレースケール/テストリリースに使用されます
7.2 test / pre-productionブランチへの統合
- テスト検証段階で、featureまたは開発ブランチをtest / pre-productionに統合します
- 推奨方法：
# （推奨）ローカルでtestingブランチに切り替え、開発メインブランチを統合
git checkout testing
git pull origin testing
git merge feature/user-management
git push origin testing
保護されていないtesting環境にのみ適用
- または開発メインブランチから一時ブランチを切り取り、testing / pre-branchにMRで統合します
7.3 main / RELEASEブランチへの統合
- mainに統合されるすべてのコードは完全なMR + CRプロセスを経る必要があります
- 統合前に変更が期待通りであるか確認します
- リリース前に30分以上前にMRを提出し、複数回のrebaseを避けます
- mainへの統合プロセス中のMRはCRを強制しません（ただし変更内容は自己確認が必要）
7.4 競合解決
personal → featureの競合：
# personalブランチでfeatureの最新コードをローカル統合
git checkout personal/user-list
git pull origin feature/user-management
# 競合を解決してコミット
git add .
git commit -m "fix: featureブランチとの統合競合を解決"
git push origin personal/user-list
# MRが自動的に更新されます
feature → mainの競合：
# featureから一時的なpersonalブランチを切り出す
git checkout feature/user-management
git checkout -b personal/sync-release
# mainの最新コードを統合
git merge main
# 競合を解決してfeatureにMR提出
# feature → mainのMRが自動的に更新されます
注意点： 競合解決のためにmainをfeatureブランチに直接統合することは禁止です（一時ブランチ経由で行う必要があります）。
- バージョンリリースとデプロイ
8.1 環境とブランチの対応関係
| 環境 | 対応ブランチ | パッキングルール |
|---|---|---|
| **本番環境（Production）** | main / RELEASE |
このブランチからのみパッキング可能 |
| **準本番環境（Pre-production）** | pre-production / pre-branch |
このブランチからのみパッキング可能 |
| **テスト環境（Testing）** | test / testing |
このブランチからのみパッキング可能 |
厳格な制約： 各環境は対応ブランチからのみパッキングデプロイでき、ブランチ間でのパッキングは禁止です。
8.2 リリースプロセス
開発完了 → testに統合 → テスト検証
→ pre-productionに統合 → 準本番検証
→ mainに統合 → 本番リリース
標準リリース手順
- 開発自己テスト：featureブランチでグレースケール環境をリリースし、グレースケールURLで自己テスト
- テスト検証：test/testingブランチに統合し、テスト環境で完全なテストを実施
- 準本番検証：pre-production/pre-branchブランチに統合し、準本番検証を実施
- 本番リリース：MRでmain/RELEASEブランチに統合し、mainからパッキングデプロイ
- 上線承認：デプロイが承認フローをトリガーし、上線前に関連責任者に事前に通知
8.3 グレースケールリリース
- 開発メインブランチ（feature）はグレースケールリリースをサポートし、開発自己テストとテスト検証に使用されます
- hotfixブランチも同様にグレースケールリリースが可能で、修正検証に使用されます
- グレースケールリリース後は、テスト担当者にグレースケールURLを提供する必要があります
8.4 バージョン管理（バックエンドサービス）
jarバージョンをアップグレードする必要があるサービスの場合、以下の手順で操作します：
- Mavenコマンドを使用して対応バージョンをアップグレード
- バージョン変更コミット後、MRでコードを統合
- バージョン変更コードがターゲットブランチに統合されたら、指定ブランチでdeployを実行
8.5 ロールバック戦略
本番リリースで問題が発生した場合、以下の優先度で処理します：
| シナリオ | 処理方法 |
|---|---|
| 問題が迅速に修正可能 | Hotfixプロセスに従い、修正後リリースし直す |
| 問題の影響範囲が大きく、迅速な修正不可能 | CI/CDプラットフォームで前の安定バージョンにロールバック |
| ロールバック後の調査が必要 | mainの前の安定コミットからhotfixブランチを作成して分析 |
ロールバック原則： サービス可用性の優先を最優先とし、その後に根本原因を調査します。ロールバック操作は関連責任者に通知し、事故レポートを記録する必要があります。
8.6 タグとバージョンマーキング
- 各本番リリース成功後、mainブランチにタグを打ってバージョンをマークすることを推奨します
- タグ命名形式：
v<メジャー>.<マイナー>.<リビジョン>、例:v1.2.0、v1.2.1 - Hotfixリリースはリビジョン番号をインクリメント、例:
v1.2.0→v1.2.1 - 機能イテレーションはマイナーバージョン番号をインクリメント、例:
v1.2.1→v1.3.0
# タグ打ちの例
git checkout main
git pull origin main
git tag -a v1.3.0 -m "feat: ユーザー管理モジュールのリリース"
git push origin v1.3.0
- ベストプラクティス
推奨プラクティス
| プラクティス | 説明 |
|---|---|
| **頻繁な統合** | 機能の一部が完成するたびにfeatureブランチに統合し、最終的に一括統合することによる競合とCR負担の増大を避けます |
| **同期の維持** | 統合前に最新のfeatureブランチコードをプルし、競合を解決してから統合します |
| **明確なコミット** | 標準化されたコミットメッセージを使用し、各コミットは1つの論理変更のみを含みます |
| **迅速なクリーンアップ** | 統合完了後、統合されたpersonalとfeatureブランチを削除します |
| **ローカルデバッグの分離** | ローカルデバッグ時にはdubbo登録グループパラメータを追加し、サービスがテスト環境に登録されるのを避けます |
| **MRの日常化** | 毎日の開発内容を開発メインブランチにMRとして提出し、単一CRの負担を軽減します |
避けるべきプラクティス
| 禁止行為 | 理由 |
|---|---|
| featureブランチでの直接開発（複数人協調時） | 複数人が同じブランチを直接修正すると競合が発生しやすい |
| 長期間コードを統合しない | 差分が蓄積し、競合リスクとCR難易度が増大する |
| 関連性のないコード変更をコミット | CR品質に影響し、ロールバックリスクが増加する |
| personalブランチをmainに直接統合 | featureブランチの統合検証とCRをスキップする |
| test/pre-productionから個人開発ブランチをプル | 環境ブランチのコードが混在し、開発ブランチが汚染される |
| test/pre-productionを個人開発ブランチに統合 | 同上、深刻なブランチ汚染 |
| testブランチで直接バグ修正 | 修正の追跡が不可能であり、他の環境に同期できない |
| Sonarスキャン未通過で強制統合 | コード品質問題の導入 |
- よくある質問（FAQ）
Q1: personal → featureの統合競合をどう解決しますか？
- personalブランチをfeatureブランチに統合するMRを提出
- 競合がありrebaseが必要と表示される
- personalブランチでfeatureブランチをローカル統合し、競合を解決
- 解決後のコードをコミットしてプッシュ
- 提出後MRが自動的に更新される
Q2: mainの最新コードをfeatureブランチに同期するには？
- featureブランチから一時的なpersonalブランチを切り出す
- 一時ブランチでmainブランチをローカル統合
- 一時ブランチをfeatureブランチにMRで統合
- 統合後、feature → mainのMRが自動的に更新される
Q3: personalブランチをmainに直接統合できますか？
推奨しません。 まずfeatureブランチに統合し、その後featureからmainに統合するべきです。完全なコードレビュープロセスを維持します。
Q4: MRでrebaseが必要と表示されたらどう処理しますか？
これはターゲットブランチに新しいコミットがあるためです。ターゲットブランチの最新コードをMRソースブランチ（例: xxx-fortest、xxx-forpre）に統合してください。個人開発ブランチには統合しないでください。そうしないと開発ブランチが汚染されます。
Q5: Sonarスキャン結果のアップロードに失敗しました？
- スキャン完了前に統合を禁止
- MRスキャンを再トリガー
- 何度も失敗する場合はMRを閉じて再提出
- それでも解決しない場合はGitLabトピックグループでGitLab担当者に連絡
Q6: ローカルデバッグでテスト環境に影響を与えないようにするには？
IDEAのJVM起動パラメータにdubbo登録グループを追加します：
-Ddubbo.registry.provider.group=zk-test-<あなたの名前の頭文字>
-Dkeycenter.dev.enable=true
グループ名はユニークにし、テスト環境と同じにしないでください。
Q7: いつtesting / pre-branchブランチにコードを統合しますか？
テスト検証完了後、ローカルで統合することを推奨します：
# 推奨方法
git checkout testing
git pull origin testing
git merge feature/user-management
git push origin testing
または開発メインブランチから一時ブランチを切り取り、testing/pre-branchにMRで統合します。
Q8: 本番リリース後に深刻な問題が発生したら？
- 影響範囲を即時評価し、関連責任者に通知
- 問題が迅速に修正可能（< 30分）なら、Hotfixプロセスに従います
- 迅速な修正が不可能なら、CI/CDプラットフォームで前の安定バージョンにロールバック
- ロールバック後、hotfixブランチを作成して根本原因を調査し、修正後に再度リリースプロセスを実行
Q9: いつタグを打ちますか？
本番環境リリースが成功した後、mainブランチにタグを打ってバージョン番号（例: v1.3.0）をマークすることを推奨します。これにより、後の追跡とロールバックが容易になります。
付録：ブランチライフサイクル図
付録A：標準開発プロセス時系列図
sequenceDiagram autonumber participant M as main / RELEASE participant F as feature/xxx participant P as personal/xxx participant T as test / testing participant Pre as pre-production M->>F: 機能ブランチ作成 F->>P: 個人開発ブランチ作成 loop 日常開発（少量頻回） P->>P: コーディング＆コミット P->>F: MR提出＋コードレビュー F->>F: レビュー通過、統合 end F->>F: グレースケールリリース＆開発自己テスト F->>T: テストブランチに統合 T->>T: テスト環境検証 F->>Pre: 準本番ブランチに統合 Pre->>Pre: 準本番環境検証 F->>M: MR提出＋コードレビュー M->>M: レビュー通過、統合 M->>M: 本番環境デプロイ＆上線 M->>M: バージョンマークのためのタグ Note over F,P: feature / personalブランチのクリーンアップ ### 付録B：Hotfix緊急修正時系列図
sequenceDiagram autonumber participant M as main / RELEASE participant H as hotfix/xxx participant T as test / testing participant Pre as pre-production M->>H: hotfixブランチ作成 H->>H: 問題修正＆コミット H->>H: グレースケールリリース＆検証 H->>M: mainにMR提出 M->>M: レビュー通過、統合 M->>M: 本番環境デプロイ M->>M: タグ打ち（リビジョン+1） M-->>T: 修正をtestに同期 M-->>Pre: 修正をpre-productionに同期 Note over H: hotfixブランチのクリーンアップ ### 付録C：ブランチ関係全体図
graph LR subgraph 永続ブランチ M["main / RELEASE<br/>🟢 本番環境"] Pre["pre-production<br/>🟡 準本番環境"] T["test / testing<br/>🔵 テスト環境"] end subgraph 一時ブランチ F["feature/xxx<br/>機能開発メインブランチ"] PA["personal/xxx-A<br/>開発者A"] PB["personal/xxx-B<br/>開発者B"] HF["hotfix/xxx<br/>緊急修正"] end M -->|"① 作成"| F F -->|"② 作成"| PA F -->|"② 作成"| PB PA -->|"③ MR統合"| F PB -->|"③ MR統合"| F F -->|"④ 統合"| T F -->|"⑤ 統合"| Pre F -->|"⑥ MR統合"| M M -->|"作成"| HF HF -->|"MR統合"| M style M fill:#d4edda,stroke:#28a745 style Pre fill:#fff3cd,stroke:#ffc107 style T fill:#cce5ff,stroke:#007bff style F fill:#f8d7da,stroke:#dc3545 style PA fill:#e2e3e5,stroke:#6c757d style PB fill:#e2e3e5,stroke:#6c757d style HF fill:#f5c6cb,stroke:#dc3545