GitHub で共同作業する

Gitは、手元で履歴を管理する仕組みでした。

変更のやり取り自体は、Git だけでもできます。 git push と git pull は Git の機能で、 共有サーバーに置いたリポジトリさえあれば、GitHub は要りません。

Git だけでは足りないのは、その周りにある共同作業の仕組みのほうです。

□ 「この変更を取り込んでいいか」を議論する場
□ 誰がいつ何を承認したかの記録
□ マージする前に自動でテストを走らせる仕組み
□ 「壊れているのでマージさせない」という強制
□ 誰がどのリポジトリに書き込めるかの管理

これらをまとめて提供しているのが GitHub です。

Git はリポジトリと履歴の仕組み。GitHub は、その Git リポジトリを中心に共同作業するサービス。

だから GitHub を使わずに Git を使うこともできます（社内 GitLab や自前のサーバーを使う会社も多い）。 ただし Issue・PR・レビュー・CI という考え方はどのサービスでもほぼ共通なので、 GitHub を覚えれば他でも通用します。

全体の流れ

新人が最初の1ヶ月で繰り返すのは、この一周です。

1. Issue を見る / 立てる          何をやるか決まる
2. ブランチを切る                 作業を分ける
3. コミットする                   手元に記録する
4. push する                      GitHub に上げる
5. Pull Request を出す            「取り込んでいいですか」と聞く
6. CI が走る                      壊していないか自動で確認される
7. レビューを受ける・直す          人が確認する
8. マージされる                   本流に入る
9. ブランチを消す                 片付ける

この一周が回せれば、業務は始められます。

Issue — 作業の単位

「やること」を1件ずつ登録するものです。バグ報告にも、機能の相談にも使います。

良い Issue の書き方

新人が最初に書くのは、たいていバグ報告です。この3つが要ります。

## 何が起きたか
注文一覧で「次へ」を押すと、2ページ目が表示されず空になる
 
## 再現手順
1. /orders を開く
2. 注文が20件以上ある状態にする
3. 「次へ」を押す
 
## 期待する動作
21件目以降が表示される
 
## 環境
Chrome 140 / staging / 2026-08-14 10:30 頃

✕ 「一覧が壊れています。直してください」
○ 上のように、再現手順・期待・実際・環境を書く

便利な書き方

PR の説明に Closes #123 と書くと、マージされた時にその Issue が自動で閉じます。 手で閉じ忘れることが無くなるので、必ず書いてください。

Pull Request — 本題

「このブランチの変更を、本流に取り込んでほしい」という依頼です。 略して PR、GitLab では MR（Merge Request）と呼びます。

出すまで

git switch -c feat/order-pagination     # ブランチを切る
# ... 変更してコミット ...
git push -u origin feat/order-pagination

push すると、GitHub の画面に「Compare & pull request」のボタンが出ます。 あるいは gh コマンドでも出せます。

gh pr create --draft --title "注文一覧のページングを修正" --body "..."

まず Draft で出す

□ 方針が合っているか、早い段階で見てもらえる
□ CI が回るので、壊していないかが分かる
□ 「今これをやっています」がチームに見える

説明に書くこと

## 何を
注文一覧のページングが2ページ目以降で空になる問題を修正
 
## なぜ
OFFSET の計算で page が 0 始まりと 1 始まりで食い違っていた（#123）
 
## どうやって
page を 1 始まりに統一し、変換をリポジトリ層に閉じた
 
## 確認したこと
- [x] staging で 3 ページ目まで表示されること
- [x] 0 件のときに空表示が出ること
- [x] 既存のテストが通ること
 
## レビューで見てほしいところ
リポジトリ層に変換を置いたが、サービス層のほうが適切か迷っています
 
Closes #123

最後の「見てほしいところ」があると、レビューの質が変わります。 迷った箇所を隠さず書くのが、結果的にいちばん早いです。

小さく出す

✕ 800行の PR   → レビューに2日かかり、指摘が形式的になる
○ 200行の PR   → 30分で見てもらえ、指摘が具体的になる

レビューできる大きさで出すのは、書く側の責任です。 大きくなりそうなら、リファクタリングと機能追加を別の PR に分けてください。

レビュー

受ける側

□ 直す      → 直してコミットを積み、「直しました」と返信する
□ 議論する  → 「こう考えたのですが、どうでしょうか」と根拠を書く
□ 分からない → 「どういう意味か教えてください」と聞く   ← これでよい

ラベルの強さ

多くのチームで、指摘の強さを接頭辞で示します。表記はチームごとに違うので、下は一例です。

nit: で承認を止めてはいけません。 逆に、自分がレビューする側になった時も同じです。

Suggested changes を使う

GitHub のレビューには、修正案を直接書ける機能があります。

```suggestion
const offset = (page - 1) * pageSize;
```

レビュアーがこれを書くと、受け取った側はボタン1つで取り込めます。 typo の指摘には特に有効で、往復が1回減ります。

自分もレビューする側になる

新人であってもレビューに参加してよいです。むしろ効果が高い。

□ 「この関数は何をしているのか分からない」   ← 最も価値のある指摘
□ 「ここでエラーになった場合はどうなりますか」
□ 「命名の意味を教えてください」

分からない箇所を指摘するのは、正当なレビューです。 読んで分からないコードは、半年後の全員にとっても分かりません。

マージの3つの方式

ボタンを押す時に選べます。チームの方針に従ってください（たいてい設定で固定されています）。 どれを使うか・レビューの書き方の作法は、まず CONTRIBUTING.md と過去の PR を見て合わせます。

wip
typo
fix
やっぱり戻す
レビュー指摘対応

壊させない仕組み

人の善意に頼らず、設定で守ります。新人が事故を起こせないようにするのが目的です。

# .github/CODEOWNERS
/src/payment/    @payment-team
/infra/          @sre-team
*.sql            @dba-team

! [remote rejected] main -> main (protected branch hook declined)

GitHub Actions

PR を出したら自動でテストが走る、あの仕組みです。

# .github/workflows/ci.yml
name: CI
on: [pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm test

新人がまずできるべきなのは、書くことより読むことです。

□ 失敗したジョブのログを開く
□ どのステップで落ちたかを見る
□ 手元で同じコマンドを打って再現する

詳しくはCI/CDで扱います。

□ まず自分でログを読む
□ 手元で再現する
□ 原因が分からなければ、そこまで調べた内容を書いて相談する

fork — 書き込み権限がない場合

社内のリポジトリは、たいてい直接ブランチを作れます。 一方 OSS には書き込み権限がありません。そこで fork を使います。

1. 相手のリポジトリを自分のアカウントへ複製する（Fork）
2. 自分の fork を clone して、ブランチを切って作業する
3. 元のリポジトリへ向けて PR を出す

gh repo fork owner/repo --clone

□ CONTRIBUTING.md  貢献の手順。ここに全部書いてある
□ CODE_OF_CONDUCT.md  行動規範
□ Issue で先に相談すべきか（大きな変更はたいてい必要）
□ 既に同じ PR が出ていないか

リポジトリを整える

自分が新しくリポジトリを作る側になった時に置くものです。

README.md              何のリポジトリか、どう動かすか   ← 最重要
.gitignore             コミットしてはいけないものを除外
LICENSE                公開するなら置く。無いと他人は使えない（後述）
CONTRIBUTING.md        貢献の手順（公開リポジトリなら）
.github/
  PULL_REQUEST_TEMPLATE.md   PR の説明の雛形
  ISSUE_TEMPLATE/            Issue の雛形
  workflows/                 CI の定義
  CODEOWNERS                 レビュー担当の割り当て

PR テンプレートを置くと、説明の質が全員分上がります。 書く項目が最初から入っているだけで、書き忘れが激減します。

秘密情報を上げない

GitHub で最も重い事故がこれです。

□ API キー・パスワード・秘密鍵
□ .env ファイル
□ 顧客のデータを含むダンプ

1. その鍵を即座に無効化し、作り直す      ← まずこれ。消すより先
2. チームと責任者にすぐ報告する
3. その鍵が実際に使われた形跡がないか、ログを確認する
4. 履歴やログからの除去は、チームの管理下で行う
5. .gitignore と push protection を見直す

予防はこの3つです。

□ .gitignore に .env を最初から入れる
□ git add . の前に git status と git diff --staged を見る
□ Secret scanning / push protection を有効にする（GitHub が検知して止めてくれる）

gh コマンド

ブラウザを開かずに操作できます。慣れると速いです。

gh auth login                    # 最初の1回
gh repo clone owner/repo
gh pr create --draft             # PR を作る
gh pr list                       # 自分に関係する PR
gh pr view 123 --web             # ブラウザで開く
gh pr checkout 123               # 他人の PR を手元で動かす   ← レビュー時に便利
gh pr checks                     # CI の結果
gh issue create
gh run watch                     # Actions の実行を眺める

gh pr checkout 123
# 実際に動かして、触ってみる

実務の落とし穴まとめ

まとめ

• Git は履歴の道具、GitHub は共同作業の場。 別物として理解する
• Issue には再現手順・期待・実際・環境を書く。書けないものは直せない
• Draft PR を早く出す。 1週間黙って作るのが最も危険
• PR には何を・なぜ・どうやって・確認したこと・見てほしいところ
• 小さく出すのは書く側の責任
• レビューの指摘は人格への評価ではない。必ず何か返す
• 新人もレビューする側に回ってよい。「分からない」は最も価値ある指摘
• Squash が多いから、PR のタイトルが履歴になる
• ブランチ保護や CI は、人の善意に頼らないための仕組み
• 秘密情報を push したら、消すのではなく無効化して作り直し、すぐ報告する

公式ドキュメント

章末問題

次の章は Docker です。ここまでで、コードを書いて共有する流れが揃いました。 今度は、そのコードをどこで動かすか——手元のサービスも依存も、 実務ではほぼすべてコンテナの中で動いています。