第5章：Git / GitHub チーム開発フロー

この章は、GitHub を初めて使うメンバー と、日々の制作を進めるメンバーの両方に向けた「チームの共通ルール」です。

方針は次の3つです。

GitHub を案件の中心にする（タスクもレビューも履歴も、チャットの記憶に頼らない）
ターミナル操作を極力減らし、Cursor の画面と GitHub のブラウザで完結させる
6名の Web 制作チームに合う、最新のシンプルな運用（複雑な Git Flow は使わない）

困ったときは第8章：よくある質問を先に見てください。

なぜ GitHub を中心にするのか

チャットや口頭だけだと、「誰が何を直したか」「どれが最新か」「本番に出してよいか」がすぐに分からなくなります。

GitHub に揃えると、次のように役割が分かれます。

置き場所	役割
Issue	「やるべきこと」のチケット。修正依頼・新規ページ・バグの受付口
作業ブランチ	自分の作業用の下書き。本番にはまだ影響しない
Pull Request（PR）	「この内容を本番に入れてよいか」の確認票。Preview URL もここに集まる
`main` ブランチ	常に本番公開してよい状態。マージ＝本番反映

[Issue で依頼] → [作業ブランチで実装] → [PR で確認] → [main へマージ] → [本番公開]

Git と GitHub の違い

初めてだと、この2つが混ざりやすいです。

名前	たとえ	実体
Git	原稿の「変更履歴をつける仕組み」	各自の PC と GitHub の両方で動く、バージョン管理の道具
GitHub	チーム共有の「編集室＋掲示板」	ブラウザで使うサービス。リポジトリ、Issue、PR、権限管理がある

Git は「いつ・誰が・何を変えたか」を記録します。
GitHub は、その記録をチームで共有し、レビュー・タスク管理・自動公開 までつなげる場所です。

私たちの組織は hokuto-com です。案件のコードは、原則すべてこの組織の private リポジトリ に置きます。契約プランは GitHub Team です。

Git のデータの流れ（ローカル ⇄ リモート）

Git を初めて使うと、「保存したのに GitHub に無い」「GitHub は新しいのに、自分の PC が古い」が起きやすいです。下の図は、自分の PC（ローカル） と GitHub（リモート） のあいだで、データがどこを通るかを示しています。

自分のPC（作業ディレクトリ・ステージング・ローカルリポジトリ）と GitHub（リモートリポジトリ）のあいだで、add / commit / push / pull / clone と Pull Request → Merge がどうつながるかを示した図

左が自分の PC、右が GitHub です。コードは一気にクラウドへ飛ぶのではなく、3つの箱を順番に通ってから チームに共有されます。

場所	図の中での役割	ここで起きること
1. 作業ディレクトリ	コード編集	Cursor でファイルを直している状態。まだ Git の履歴には残っていない
2. ステージングエリア	変更の準備	`add`（準備する）。「次の保存に含めるファイル」を選ぶ箱
3. ローカルリポジトリ	変更履歴の保存	`commit`（履歴に記録）。自分の PC の中だけの確定。他の人にはまだ見えない
リモートリポジトリ	GitHub の共有場所	`push` で送る。チームが見られ、PR や本番公開の起点になる

矢印の意味は、次のとおりです。

add（準備する） … 編集したファイルを「今回の保存セット」に入れる
commit（履歴に記録） … そのセットを、自分の PC の履歴として確定する
push（クラウドへ送信） … ローカルの履歴を GitHub へ送る。送るまで他の人にも Cloudflare にも届かない
pull / clone（手元へ取得） … GitHub の最新を自分の PC へ取り込む。初回の丸ごとコピーが clone、そのあとの差分取り込みが pull
Pull Request → Merge … GitHub 上で「入れてよいか」を確認し、問題なければ main に合流する

「自分の PC で保存した」と「チームの最新になった」は別物です。commit しただけならローカルまで。チームに見せる・Preview を出すには push が必要、と覚えてください。

画面で使う機能の見取り図

GitHub のリポジトリを開くと、上部にタブが並びます。よく使うものだけ覚えれば十分です。

タブ / 機能	日本語での呼び方	何をする場所か
Code	コード	ファイルの中身を見る。クローン用 URL もここ
Issues	課題	タスク・修正依頼・バグを1件ずつ管理する
Pull requests	プルリクエスト	本番に入れる前の確認・承認・マージ
Actions	アクション	自動チェックや自動処理の実行履歴（上級者向け）
Projects	プロジェクト	カンバン（To do / In progress / Done）で案件全体を俯瞰する
Settings	設定	権限、Rulesets、シークレット。オーナー以外は普段触らない
Insights	インサイト	誰がどれだけ貢献したかなどの統計。必須ではない

リポジトリ以外にも、組織全体で使う機能があります。

機能	何のためか
Organization（組織）	`hokuto-com` 全体の入れ物。メンバー・権限・共通ルールをまとめる
Teams	組織内の班。例: `directors` / `designers` / `engineers`
Rulesets	「`main` に直接書き換えさせない」などの安全ルール
Dependabot	使っている npm パッケージの脆弱性を知らせ、更新 PR を出す
通知（Notifications）	自分宛のメンション、レビュー依頼、CI 結果を知らせる
2FA（二要素認証）	パスワードに加え、スマホ確認を必須にするログイン保護

用語をたとえで覚える

コードを書く人以外も、この7語だけ押さえれば日常会話についていけます。上の図（ローカル ⇄ リモート）と対応させて覚えると、迷子になりにくいです。

用語	たとえ	チームでの意味
リポジトリ（repo）	案件フォルダ	1案件＝1リポジトリ。例: `hokuto-com/example-lp`
クローン（clone）	共有フォルダを自分の PC にコピー	初回だけ行う。第0章の手順
ブランチ（branch）	自分用の下書き用紙	`main` を汚さず、機能ごとに分かれて作業する
コミット（commit）	「ここまで保存」の区切り	意味のまとまりごとに残す。後から理由が分かるようにする
プッシュ（push）	自分の保存を GitHub へ送る	送らないと、他の人にも Cloudflare にも届かない
プル（pull）	GitHub の最新を自分の PC へ取り込む	作業開始前と、レビュー前に行う
マージ（merge）	下書きを本番原稿に取り込む	PR 承認後に `main` へ入れる操作

組織「hokuto-com」の標準体制

6名の制作チームなので、権限はシンプルにします。細かい班分けで迷うより、「誰でも Issue を立てられ、誰でもレビューに参加できる」状態を優先します。

メンバーの役割と GitHub 上の権限

役割	GitHub での目安権限	主な仕事
オーナー（1〜2名）	Organization owner	招待、Rulesets、請求、危険な設定変更
ディレクター / 進行	リポジトリ Write	Issue 起票、ラベル付け、Preview 検収、マージ判断
デザイナー	リポジトリ Write	Figma 確定、Preview での見た目確認、必要なら PR コメント
コーダー / エンジニア	リポジトリ Write	ブランチ作成、実装、PR 作成、コードレビュー

Write 権限があれば、Issue・ブランチ・PR は一通り使えます。Admin は案件ごとに増やさず、オーナーに寄せます。

リポジトリの作り方（原則）

1案件＝1リポジトリ
公開範囲は Private
新規案件はテンプレートから作る（手順は第0章）
リポジトリ名は英数字とハイフン（例: client-name-lp）
説明欄に「クライアント名 / 本番 URL / 担当ディレクター」を書いておく

推奨する GitHub Team（班）

必須ではありませんが、招待と権限の付け替えが楽になります。

Team 名	入れる人	使い方
`directors`	進行・ディレクター	Issue の一次対応、マージ判断
`designers`	デザイナー	デザイン確認のメンション先
`engineers`	コーダー	コードレビューのメンション先

新しい案件リポジトリを作ったら、上記3チームを Write で追加します。個人を1人ずつ追加し続ける運用は避けます。

ブランチ戦略（GitHub Flow）

大規模開発向けの「develop / release / hotfix を何本も持つ Git Flow」は使いません。案件サイトでは、main と作業ブランチの2層だけ が事故が少なく、Preview とも相性が良いためです。

[main（本番）] ────────────────────────────────●（マージ＝本番自動公開）
     ▲                                        │
     │ PR + Preview 確認                       │
     │                                        ▼
[feat/contact-form] ──●──●──●（Cursor からプッシュ）

main：常に本番公開してよい状態。直接の編集・直接プッシュは禁止（Rulesets で技術的にも止める）
作業ブランチ：1 Issue（または1つのまとまった作業）につき 1本。使い終わったら削除する

作業ブランチの命名

種類	接頭辞	例
新機能・新規ページ	`feat/`	`feat/about-page`, `feat/contact-form`
見た目・文言・バグ修正	`fix/`	`fix/header-logo`, `fix/typo`
リファクタ（動きは同じ、中身の整理）	`refactor/`	`refactor/microcms-sdk`
ドキュメント・設定だけ	`chore/`	`chore/add-pr-template`

枝の名前は 英語・ハイフン・短め にします。日付や自分の名前は入れません（履歴を見れば分かるため）。

1案件の標準サイクル

初期設定が終わったあとは、すべての作業がこの順で進みます。

1. 【GitHub】Issue を立てる（例: #12 お知らせ詳細のUI）
        │
        ▼
2. 【Cursor】feat/news-detail ブランチを切って実装・コミット
        │
        ▼
3. 【GitHub】PR を出す（Cloudflare が Preview URL を自動投稿）
        │
        ▼
4. 【確認】Preview で見た目と動き、コード差分で実装をレビュー
        │
        ▼
5. 【マージ】Squash and merge
        ├─ 本番が自動更新される
        └─ Issue #12 が自動で閉じ、Project 上も Done になる

Issue（タスクの受付口）

Issue は「依頼メモ」ではなく、後から他の人が作業できるチケット です。口頭やチャットで受けた内容も、実装に入る前に Issue 化します。

立て方

案件リポジトリを開く
Issues タブ＞ New issue
タイトルは「何をどうしたいか」が主語（例: お知らせ詳細ページのカード余白をデザイン通りにする）
本文に、再現手順・Figma URL・期望・スクリーンショットを書く
Assignees（担当者）、Labels（種類）、必要なら Projects（カンバン）を付ける
Submit new issue

本文の型（コピー用）

## やりたいこと
お知らせ詳細の見出し下の余白を、Figma の 40px に合わせたい。

## 対象
- ページ: /news/[id]
- Figma: https://www.figma.com/design/xxxx?node-id=12-34
- 実機: iPhone Safari

## 完了の定義
- 余白がデザインと目視で一致する
- 他ページの見出しスタイルを壊していない

ラベルの標準セット

各リポジトリに、最低限このラベルを用意します（Settings ＞ Labels）。色は自由ですが、名前は統一します。

ラベル	使うとき
`feat`	新しいページ・機能
`fix`	崩れ・バグ・文言修正
`design`	見た目の確認が主目的
`content`	CMS 入稿やテキスト差し替え
`chore`	設定・依存関係・ドキュメント
`blocked`	先方確認待ちなど、こちらでは進められない
`urgent`	公開直前の障害など、当日中に見るもの

Issue を実装につなげる

コーダーは、コミットメッセージか PR 本文に次のいずれかを書きます。マージと同時に Issue が自動で閉じます。

closes #12
fixes #12

複数 Issue を1 PR にまとめないのが原則です。例外（同じ原因の修正が複数 Issue に分かれている場合）だけ、本文に複数の closes を並べます。

Project（カンバン）

Projects は、Issue と PR をカードとして並べるボードです。スプレッドシート代わりに、案件の「今どこまで進んでいるか」を共有します。

6名規模では、次の運用が扱いやすいです。

組織 hokuto-com に 案件ごとの Project を1つ作る（複数リポジトリにまたがってもよい）
ビューは Board（カンバン）を標準にする
列（Status）は次の4つに固定する

列	意味	誰が動かすか
Backlog	やる予定。まだ着手しない	ディレクター
In progress	実装中	着手した本人
In review	PR が出て、確認待ち	PR を出した人
Done	マージ済み、または不要になった	マージした人 / ディレクター

Issues 画面右上の Projects から既存ボードへ追加できます。PR にも同じ Project を付け、レビュー中の作業が見えるようにします。

Cursor（GUI）での日常作業

ターミナルで Git コマンドを覚えなくても、日々の作業は進みます。

1. 最新の `main` を取り込む

作業を始める前に、他メンバーのマージを自分の PC へ入れます。

Cursor 左下の 同期アイコン（回転する矢印） をクリックする
または Agent に「最新の main を取り込んで」と頼む

2. 作業ブランチを切る

Cursor 左下のブランチ名（最初は main）をクリック
新しいブランチの作成 を選ぶ
feat/news-list のように入力して確定

必ず main から切る のが原則です。古い作業ブランチの上に、別作業の枝を重ねないでください。

3. 実装してコミットする

Composer（Agent モード）に Issue 番号と Figma URL を渡して実装する
左サイドバーの ソース管理（枝分かれアイコン） を開く
変更ファイルを確認する（.env が入っていないこと）
メッセージを入れて コミット

コミットメッセージは、次の形に揃えます。

feat: お知らせ一覧ページのUI実装

closes #12

接頭辞	使うとき
`feat:`	新しい機能・ページ
`fix:`	バグや見た目の修正
`refactor:`	動きは変えず整理
`chore:`	依存関係や設定
`docs:`	ドキュメントのみ

1コミットは「後から読んで意味が通じる塊」にします。「とりあえず」を連発するより、区切りのよいところで保存します。

4. GitHub へプッシュする

ソース管理ビューの 変更の同期 または ブランチの公開 を押します。これで GitHub 上に作業ブランチが届きます。

Pull Request（本番に入れる前の確認票）

PR は「コードを送る箱」ではなく、チームで「入れてよいか」を判断する場 です。モダン制作では、ここに Cloudflare の Preview URL が自動で付きます。

[作業ブランチをプッシュ]
        │
        ▼
[GitHub で PR 作成]
        │
        ▼
[Cloudflare が Preview URL をコメント]
        │
        ├─ ディレクター / デザイナー：ブラウザと実機で見た目・文言・動き
        └─ エンジニア：Files changed で差分を確認
        │
        ▼
[Approve のあと Squash and merge]
        │
        ▼
[main 更新 ＝ 本番デプロイ]

PR の作り方

プッシュ直後、GitHub のリポジトリトップに出る Compare & pull request を押す
出ない場合は Pull requests ＞ New pull request で、base を main、compare を自分の枝にする
タイトルはコミットと同じ粒度（例: feat: お知らせ一覧ページのUI実装）
本文に確認してほしい点を書く
Reviewers に確認者を指定する（デザイン確認ならデザイナー、実装確認ならエンジニア）
未完成なら Create draft pull request、確認してよければ Create pull request

PR 本文の型（コピー用）

## 概要
Issue #12 のお知らせ一覧 UI を実装しました。

## 確認してほしいこと
- [ ] Preview でカードの余白・フォントが Figma と一致するか
- [ ] 記事 0件のとき空状態になるか
- [ ] スマホ幅で画像がはみ出ないか

## Preview
Cloudflare ボットのコメントを見てください。

Draft と Ready

状態	使うとき
Draft	途中経過の共有。まだレビューしなくてよい
Ready for review	確認してほしい。レビュアーに通知が飛ぶ

下書きのままマージはしません。準備ができたら Ready for review に切り替えます。

レビューの見方（非エンジニア向け）

コードが読めなくても、PR は確認できます。

Conversation タブで Cloudflare ボットの Preview URL を開く
PC とスマホ実機で見る（見た目・文言・リンク・フォーム）
気になる点は、画面の Files changed で該当ファイルにコメントするか、Conversation に箇条書きする
問題なければ Review ＞ Approve。戻してほしいときは Request changes

レビューの種類	意味
Comment	意見だけ。マージは止めない
Approve	入れてよい
Request changes	直してから再確認したい

エンジニアのコード確認

Files changed で意図しないファイル（.env、巨大画像、関係ないページ）が入っていないか見る
コンソールエラーや明らかな崩れは Preview でも確認する
指摘は「直してほしいこと / 任意の提案」を分ける

新しいコミットが追加された PR は、前回の Approve をやり直します（Rulesets の「古い承認を無効化」）。

マージのルール

レビューが揃い、Preview で合格したらマージします。

使うマージ方法は Squash のみ

GitHub の画面には3種類出ることがありますが、チーム標準は Squash and merge だけ です。

方法	使うか	理由
Squash and merge	使う	作業中の細かいコミットが1つにまとまり、`main` の履歴が読みやすい
Create a merge commit	使わない	`main` に合流用のコミットが増え、履歴が枝分かれして見える
Rebase and merge	使わない	操作を間違えると履歴が書き換わり、初学者に事故が起きやすい

マージ後の設定も揃えます。

Automatically delete head branches をオンにする（マージ済み枝を自動削除）
ローカルに残った古い枝は、次の作業前に main へ戻してから消し、新しい枝を切る

マージしてよい条件

次をすべて満たしたら、ディレクターまたは実装者がマージします。

必要な人の Approve が1件以上 ある
Preview で確認項目を見終わっている
「古い指摘のまま残っている会話」を解決している（Resolve conversation）
Dependabot や Actions の必須チェックが付いている場合、それが成功している

自分だけで完結する超小修正でも、Approve なしの自己マージはしない のが Team プランを活かす最低ラインです。6名いれば、必ずもう1人が見られます。

Rulesets（main を守るルール）

昔はリポジトリごとに Branch protection rule を付けていました。2025年以降の Team プランでは、Rulesets（ルールセット） が推奨です。

Rulesets の利点は次です。

組織 hokuto-com に1回作れば、新規リポジトリにも同じルールを適用できる
「評価モード（Evaluate）」で、本番適用前に「誰が止まったか」を確認できる
管理者だけルールを素通り、という抜け穴を減らせる

組織に1つ置く標準 Ruleset

オーナーが Organization settings ＞ Repository ＞ Rulesets で作成します。

項目	設定値
名前	`Protect main`
Enforcement	最初の1週間は Evaluate、問題なければ Active
対象リポジトリ	組織内の private リポジトリすべて（テンプレート含む）
対象ブランチ	`main`
Require a pull request	オン
Required approvals	1
Dismiss stale reviews	オン（新しいコミットが来たら再承認）
Require conversation resolution	オン
Block force pushes	オン
Restrict deletions	オン（`main` を消せない）
Require status checks	Cloudflare や CI を後から必須化してよい。最初は必須にしなくてよい
Bypass	緊急時のみオーナー。普段は使わない

Evaluate のあいだは作業を止めません。Insights で「このルールが効いていたら止まった操作」を見てから Active にします。

リポジトリ単体の Classic な Branch protection と Rulesets が両方あると、より厳しい方が勝ちます。新規案件では Classic 側は作らず、組織 Ruleset に寄せます。既存リポジトリに古い保護が残っている場合は、Ruleset を Active にしたあと Classic を外します。

セキュリティと自動メンテ

Web 制作でも、次だけは全員が守ります。

2FA（二要素認証）

組織メンバーは 2FA 必須 にします（Organization settings ＞ Authentication security）。パスワードが漏れても、スマホ側の確認がないと入れません。

秘密情報を GitHub に置かない

置いてよい	置いてはいけない
`.env.example`（キー名だけの見本）	`.env`（本物の API キー）
公開してよい画像・コピー	クライアントの未公開資料で契約上出せないもの

間違えてコミットした場合は、チャットで「消した」と済ませず、オーナーにすぐ共有します。履歴に残るため、キーの無効化と再発行が必要です。詳細は第8章 FAQ を見てください。

Dependabot

npm の脆弱性を GitHub が監視し、更新 PR を自動で出します。Team プランで使えます。

セキュリティ更新の PR は、Preview が壊れないことだけ確認して早めにマージする
毎週大量に来るバージョン更新まで自動追従する必要はない（サイト案件ではセキュリティ更新を優先）

テンプレートリポジトリに .github/dependabot.yml を置いておくと、新規案件にも継承されます。

version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
    open-pull-requests-limit: 5

GitHub Actions

Actions は「プッシュや PR をきっかけに、GitHub 側で自動作業する仕組み」です。必須ではありません。

6名チームでの使いどころは、次程度に留めます。

後から「PR ごとに npm run build を回して、壊れたらマージ不可」を足す
本番デプロイそのものは Cloudflare 側 に任せる（二重管理にしない）

通知とメンション

GitHub は、放っておくとメールが増えます。次だけ設定すれば十分です。

自分に関係あるもの: Assignees にされた Issue、Reviewers にされた PR、@名前 メンション
レビューを頼むときは、チャットだけで終わらせず PR の Reviewers に入れる（通知が確実に届く）
班全体に振るときは @hokuto-com/designers のように Team メンションを使う
画面右上のベル（Notifications）を、1日1回は開く

Watch（リポジトリの購読）は、自分が担当する案件だけにします。全リポジトリを Watch すると埋もれます。

テンプレート（あると初学者が迷わない）

astro-starter-template など、新規案件の元になるリポジトリへ次を置きます。案件ごとに毎回書かなくてよくなります。

ファイル	効果
`.github/ISSUE_TEMPLATE/task.yml` など	Issue 作成時に入力欄が出る
`.github/PULL_REQUEST_TEMPLATE.md`	PR 本文の型が最初から入る
`.github/dependabot.yml`	依存関係の更新 PR が自動で来る

やらないこと（6名チームでは過剰）

最新機能でも、今の規模では導入しません。

やらないこと	理由
Git Flow（develop / release を常設）	Preview と本番の二層で足りる。枝が増えると「どれが正しいか」が分からなくなる
CODEOWNERS 必須レビュー	担当が固定しすぎると、休暇のときマージできない
Merge queue	同時マージが常時起きる規模ではない
署名付きコミット必須	初期導入コストが高く、制作フローの妨げになる
Issue 以外の二重管理（スプレッドシートと看板を両方正とする）	正は GitHub に1つ。他ツールはリンクだけ

公開前の品質項目そのものは第7章を使います。GitHub 上の「入れてよいか」の判断と、公開当日チェックリストは役割が違います。