GitHub運用がバラバラだった頃
弊社EastCloudは受託開発と自社プロダクト開発の両軸で事業を進めている。GitHubは早い段階から導入していたが、運用ルールが定まらないまま開発を続けていた。
プロジェクトが増え、メンバーが増えてくると、ルールの不在が目に見えて開発効率に影響し始めた。そこで社内のGitHub運用を標準化するガイドを作成した。
ここではガイド作成の背景、内容のポイント、導入後に確認できた効果をまとめる。
整備前に抱えていた4つの課題
ガイド作成にあたって社内の開発フローを棚卸しした。見えてきた課題は4つあった。
- ブランチ運用の属人化 — 命名規則がなく、誰がどのブランチで何を開発しているか把握できていなかった
- コミット履歴の不透明さ — コミットメッセージが「修正」「対応」ばかりで、変更の意図を後から追えなかった
- コードレビュー文化の不在 — PRを経由せずmainブランチへ直接pushする運用が常態化していた
- 非エンジニアメンバーの疎外 — PMやデザイナーがGitHubの画面を見ても開発状況がまったくわからなかった
いずれも少人数チームで起こりがちな問題だ。暗黙知で回せる段階はすぐに限界を迎える。メンバーが5人を超えたあたりから、明文化されたルールがないと開発効率は目に見えて落ちる。
ガイドの全体構成
作成したガイドは10章+付録の構成にした。エンジニアだけでなくPMやデザイナーも読める内容にすることを重視している。
| 章 | 内容 | 対象者 |
|---|---|---|
| 1. ブランチ戦略 | main/develop/feature/hotfixの運用フロー | エンジニア |
| 2. コミットメッセージ規約 | type付きメッセージのルール | エンジニア |
| 3. Issue運用 | タスク管理の最小単位としてのIssue活用 | 全員 |
| 4. PR運用 | PRフロー・タイトル規約・マージ方針 | エンジニア |
| 5. コードレビュー観点 | 正確性・セキュリティ・可読性・パフォーマンス・テスト | エンジニア |
| 6. GitHub Projectsボード運用 | カンバンのステータス管理 | 全員 |
| 7. CI/CD方針 | GitHub Actionsによる自動化 | エンジニア |
| 8. 日常の開発フロー | 一連の作業手順まとめ | エンジニア |
| 9. よくある質問 | コンフリクト対応・誤push対応など | エンジニア |
| 10. 非エンジニア向け基礎 | GitHubの基本概念と3つのアクション | PM・デザイナー |
| 付録 | Gitコマンド早見表 | エンジニア |
では各章のポイントを掘り下げていく。
ブランチ戦略 — 4種類に絞った理由
小規模チーム向けのブランチ戦略としてはGitHub Flowがよく推奨される。mainブランチとfeatureブランチだけで回すシンプルなモデルだ。ただ、弊社は受託開発も手がけており、リリースタイミングが顧客との調整で決まる案件が多い。
GitHub Flowはmainにマージしたらすぐデプロイする前提だ。リリースを溜めてまとめて出す受託開発には合わない。そこでGit Flowをベースに、ブランチを4種類に絞った簡略版を採用した。releaseブランチはリリースフローが複雑化するまで導入しない。
| ブランチ | 用途 | 命名規則 |
|---|---|---|
main | 本番リリース済みコード | — |
develop | 開発統合ブランチ | — |
feature/* | 新機能・改善 | feature/<issue番号>-<説明> |
hotfix/* | 本番の緊急修正 | hotfix/<issue番号>-<説明> |
ブランチ名はケバブケースで統一した。feature/6-authentication-api、hotfix/23-fix-login-errorといった形だ。Issue番号を先頭に置くことで、どのタスクに対応するブランチかひと目でわかる。
運用面で大事にしたのは、mainだけでなくdevelopへの直接コミットも禁止した点だ。すべての変更はfeatureブランチからPRを経由してdevelopにマージする。加えてhotfix/*ブランチはmainから作成し、修正後はmainとdevelopの両方にマージして修正漏れを防ぐ。
ここで欠かせないのがGitHubのBranch Protection Rule（ブランチ保護ルール）だ。mainへの直接pushをシステム的に禁止した。ルールは口頭で伝えるだけでは定着しない。ツールで強制するほうが確実だ。
なおGitHubは2023年7月にRepository Rulesetsという新しい保護機能をGA（一般提供）している。従来のBranch Protection Ruleと併存しており、Organization全体に統一ルールを適用したい場合はRulesetsのほうが柔軟だ。ただし単一リポジトリの保護なら従来のBranch Protection Ruleで足りるため、今回はそちらを採用した。
コミットメッセージ規約 — 6つのtypeで変更意図を明確にする
コミットメッセージの統一にはConventional Commitsの考え方をベースにしたシンプルなフォーマットを採用した。
<type>: <概要>scopeは省いた。小規模チームではモジュール境界がまだ流動的で、scopeの粒度をルール化すると逆に混乱する。概要は日本語でも英語でもよい。
typeは6つに絞った。
| type | 用途 | 例 |
|---|---|---|
feat | 新機能 | feat: ログインAPI追加 |
fix | バグ修正 | fix: トークン有効期限の修正 |
refactor | リファクタリング | refactor: バリデーション処理を分離 |
docs | ドキュメント | docs: API仕様書を追加 |
test | テスト | test: 認証コントローラのテスト追加 |
chore | ビルド・設定・その他 | chore: docker-compose設定を更新 |
Issue番号はコミットメッセージには含めず、PRタイトルで紐付ける運用にした。コミットメッセージは変更の意図だけに集中させ、タスク管理の情報はPRに寄せて役割を分けている。
Issue運用とGitHub Projectsボード
Issueをタスク管理の最小単位にする
ガイドではIssueをタスク管理の最小単位と位置づけた。すべての作業はIssueを起点にする。急ぎのhotfixでも事後でIssueを作成するルールだ。
IssueにはラベルをつけてProjectsボードと連携する。推奨ラベルとしてbackend、frontend、infrastructure、bug、documentationを用意した。プロジェクトに応じて追加・変更できる。
Projectsボードのステータス管理
GitHub Projectsボードのステータスは4つに絞った。
| ステータス | 説明 |
|---|---|
| Todo | 未着手 |
| In Progress | 作業中 |
| In Review | PR作成済み・レビュー待ち |
| Done | 完了 |
Issueに着手したら必ずIn Progressに変更する。PRを作成したらIn Reviewに変更する。さらに週次でボードの棚卸しを行い、停滞しているIssueがないか確認する。この棚卸しがないとボードは簡単に形骸化するため、週次ミーティングの固定アジェンダに組み込んだ。
PR運用 — タイトル規約とマージ方針
PRタイトルにIssue番号を必須化
PRタイトルにはIssue番号を必ず含めるルールにした。フォーマットはこうだ。
feat[#6]: 認証API実装
fix[#12]: ユーザー一覧の表示不具合を修正type[#Issue番号]: 概要の形式で、コミットメッセージ規約のtypeを流用している。PRタイトルを見ただけで、どのタスクの、どんな種類の変更かわかる。
PRテンプレートの標準化
PRテンプレートは.github/PULL_REQUEST_TEMPLATE.mdに配置した。セクションは概要・対応Issue・変更内容・確認事項の4つだ。
特に効いたのが確認事項のチェックリストだ。「ローカルで動作確認済み」「テスト追加・更新済み」「既存機能への影響なし」の3点をセルフチェックさせることで、レビュアーの負担を下げた。
加えてPR本文にcloses #<Issue番号>を記載すると、マージ時にIssueが自動クローズされる。閉じ忘れを防ぐ仕組みとして活用している。
マージ方針の使い分け
マージ方法は2つを使い分ける。
| 種別 | マージ方法 | 理由 |
|---|---|---|
機能ブランチ → develop | Squash and merge | 作業途中の細かいコミットを1つにまとめて履歴を整理する |
develop → main | Merge commit | リリース単位のマージ履歴を明示的に残す |
Squash and mergeを使えば、featureブランチ内で何度コミットしてもdevelopの履歴はPR単位で1コミットに整理される。コミットの粒度を気にせず開発できるため、開発者の心理的なハードルが下がる。
レビュー方針
レビューは最低1名のApproveを必須にした。ただし軽微な修正（typo、コメント追記等）はセルフマージを許可している。すべてのPRに厳格なレビューを求めると小規模チームでは回らない。重要な変更にレビューリソースを集中させるための割り切りだ。
コードレビュー観点 — 5つの視点でチェックする
レビュアーが何を見ればいいか迷わないよう、コードレビューの観点を5つに分けて明文化した。
正確性 — ビルドが通ること。Issueの要件を満たしていること。境界値やエッジケースが考慮されていること。
セキュリティ — SQLインジェクション対策でパラメータバインドを使っているか。XSS対策でユーザー入力値をエスケープしているか。機密情報がハードコードされていないか。CSRF対策が必要な箇所で実装されているか。
可読性・保守性 — 変数名・関数名がその役割を表しているか。1つの関数が1つの責務に集中しているか。デバッグ用コード（console.log等）が残っていないか。マジックナンバーが定数化されているか。
パフォーマンス — N+1クエリが発生していないか。ループ内で不要なAPIコールがないか。大量データの処理でページネーションが考慮されているか。
テスト — 変更に対応するテストが追加されているか。正常系・異常系の両方がテストされているか。
この5観点をガイドに書いたことで、レビューの属人化を防げた。新しくレビュアーになったメンバーでも、何をチェックすべきか迷わない。
CI/CD方針 — GitHub Actionsによる自動化
ガイドにはCI/CD方針も盛り込んだ。GitHub Actionsで以下のタイミングに自動化を走らせる。
| トリガー | 実行内容 |
|---|---|
| PR作成・更新時 | Lint + ビルド + テスト |
developへのマージ | ステージング環境へデプロイ |
mainへのマージ | 本番環境へデプロイ |
CIのチェック項目はコードフォーマット（Lint）、ビルド成功、ユニットテスト通過の3つ。CIが失敗しているPRはマージしない。Branch Protection RuleでCIパスを必須条件に設定すれば、この運用もツールで強制できる。
非エンジニア向けGitHub基礎 — 社内で最も反応が良かったセクション
ガイドの中で社内から最も反応が良かったのがこのセクションだ。
PMやデザイナーがGitHub上で開発状況を把握できるよう、基本概念をスクリーンショット付きで解説した。技術用語は極力使わず、ブランチはWord文書の変更履歴を別ファイルに分けて管理するイメージ、PRはGoogleドキュメントの提案モードに近い仕組み、という比喩で説明している。
非エンジニアに覚えてもらった3つのアクション
1. Issueにコメントする
仕様の質問や確認をGitHub上で行い、情報を一元管理する。Slackやメールに散らばっていた仕様確認がIssueに集約されるだけで、後からの振り返りが格段に楽になる。
2. PRのFilesタブを確認する
コードの詳細はわからなくても、何が変わったかを視覚的に把握できる。緑の行が追加、赤の行が削除。この見方だけ覚えてもらった。
3. PRにApproveする
PM承認をGitHub上で行い、口頭承認によるコミュニケーションロスをなくす。PR画面の「Review changes」から「Approve」を選ぶだけで完了する。
この3つを徹底したことで、開発プロセスの透明性が大幅に上がった。PMが開発状況をリアルタイムで把握できるようになり、チーム全体の連携が目に見えてスムーズになった。Projectsボードの見方もあわせて説明し、PMがタスク進捗を一覧で確認できるようにしている。
導入後の定量効果
ガイドを展開してから約1ヶ月後に振り返りを行った。確認できた成果は次の通りだ。
| 指標 | 導入前 | 導入後 |
|---|---|---|
| mainへの直接push | 週に数回発生 | ゼロ |
| コミットメッセージ規約の遵守率 | ほぼ0% | 約80% |
| PRの説明記述率 | 約20% | 約90% |
| 非エンジニアのGitHub利用 | ほぼなし | PMがIssueコメントを日常的に利用 |
遵守率が100%に届いていないのは正直なところだ。typeの使い分け自体はほぼ100%守られている。ただ概要の書き方にはまだばらつきがある。ここは引き続き改善を進めている。
定性面で大きかったのは、PMがGitHub上でIssueコメントを行うようになった点だ。以前はSlackでの口頭確認が中心で、仕様の決定経緯がよく流れていた。Issueに記録が残るようになったことで情報の散逸を防げるようになった。
ガイド作成で意識した3つの原則
今回のガイド作成を通じて、強く意識した原則が3つある。
ルールを最小限にすること。 覚えきれないルールは形骸化する。コミットメッセージのtypeは6つ、Projectsボードのステータスは4つ、非エンジニアに覚えてもらうアクションは3つ。小規模チームに必要十分な数に絞り、確実な定着を狙った。
ツールで強制すること。 Branch Protectionによるmainへの直接push禁止、CIパス必須によるマージ制限、PRテンプレートによる説明欄の標準化。人の注意力に頼るルールはいずれ破綻する。守らざるを得ない環境を作ることが運用定着への最短経路だ。
非エンジニアを巻き込むこと。 開発プロセスの透明性はチーム全体の生産性に直結する。エンジニアだけが使うツールのままではGitHubの価値は半減する。PMやデザイナーも参加できる設計にしたことで、コミュニケーションコストが下がった。
よくある質問
Q. GitHub FlowではなくGit Flowベースにした理由は?
弊社は受託開発も手がけており、リリースタイミングが顧客調整で決まることが多い。GitHub Flowはmainにマージしたらすぐデプロイする前提だ。リリースを溜めてまとめて出す運用にはフィットしない。developブランチを挟む簡略版Git Flowのほうが実情に合った。
Q. コミットメッセージにscopeを入れなかった理由は?
小規模チームではモジュール境界がまだ流動的で、scopeの粒度をルール化すると混乱を招く。typeと概要だけのシンプルなフォーマットにして、覚えやすさと定着率を優先した。
Q. 非エンジニアにGitHubを使ってもらうのは現実的か?
弊社ではうまくいった。覚えてもらうアクションをIssueコメント、PRのFilesタブ確認、Approveの3つに絞ったことが大きい。いずれもWebブラウザ上で完結するため学習コストは低い。
Q. Squash and mergeとMerge commitを使い分ける理由は?
featureブランチでは試行錯誤で細かいコミットが積まれがちだ。Squash and mergeで1コミットにまとめれば、developの履歴はPR単位で整理される。一方、develop→mainはリリース単位の記録として残したいため、Merge commitでマージ履歴を明示する。
Q. ガイドの分量はどのくらいが適切?
今回は本文10章+付録の構成だった。各章を独立して読めるようにしたので、エンジニアは1〜9章、非エンジニアは10章とProjectsボードの章だけ読めば運用を始められる。全部読まなくても始められる設計にしておくのが大事だ。
Q. Branch Protection RuleとRepository Rulesetsはどちらを使うべき?
単一リポジトリの保護ならBranch Protection Ruleで十分だ。Organization全体に統一ルールを適用したい場合や、複数リポジトリに同じ保護設定を展開したい場合はRepository Rulesetsが向いている。両者は併存できるため、まずBranch Protection Ruleから始めて必要に応じて移行するのがよい。
関連記事
- 情報収集を全自動化する方法 ― RSS・LLMキュレーション・チャット配信の実装ガイド — チーム内の情報共有を仕組み化したい場合はこちら
ガイドのダウンロード
今回作成したガイドを、汎用的に使える形に整理したPDF資料として公開している。自社の状況に合わせてカスタマイズして使ってほしい。
小規模チームこそ早い段階で開発プロセスを整備する意味がある。人数が増えてからでは、ゼロから構築するよりも遥かにコストがかかる。
