メインコンテンツへスキップ
見出し画像

数分の設定でチーム開発を楽にするGitHubの便利小技10選

    GitHubを使ったチーム開発では、必ずしも大規模なCI/CD基盤を構築しなくても、少しの設定や数行のGitHub Actionsを追加するだけで、開発体験を大きく改善できる。
    たとえば、次のような小さなストレスは経験された方も多いだろう。

    • マージ済みブランチが大量に残る

    • PRのチェック完了を待ってから、手動でマージしている

    • コミットを追加するたびに古いCIも動き続ける

    • READMEを修正しただけなのに、すべてのテストが実行される

    • PRごとに説明の書き方がバラバラ

    • レビュアーを毎回手動で指定している

    一つひとつは小さな問題だが、毎日繰り返すと意外と大きな負担となる。
    この記事では、導入コストが低く、再現性が高く、チーム開発ですぐ効果を感じやすいGitHubの設定やGitHub Actionsの小技を紹介しよう。

    1. マージ済みブランチを自動削除する

    PRをマージしたあと、作業ブランチを手動で削除していないだろうか。
    GitHubには、マージされたPRの元ブランチを自動削除する機能が標準で用意されています。GitHub Actionsを書いてCIラインを引く必要はない。

    リポジトリで次の設定を有効にする。

    Settings
      └ General
          └ Pull Requests
              └ Automatically delete head branches

    これだけで、PRがマージされたときに対象ブランチが自動削除される。
    特に、短命なFeature Branchを大量に作るチームでは効果が大きい設定だ。

    なお、保護ルールやRulesetによって削除が禁止されているブランチは、自動削除されない場合がある。

    2. CI完了後にPRを自動マージする

    レビューは終わっているのに、CIが完了するまで待ち、完了後にもう一度GitHubを開いてマージする。
    この小さな待ち時間も、Auto-mergeを使うことでなくせる。

    まず、リポジトリでAuto-mergeを有効にする。

    Settings
      └ General
          └ Pull Requests
              └ Allow auto-merge

    その後、PR画面で`Enable auto-merge`を選択する。

    必要なレビューやStatus Checkがすべて通過すると、PRが自動的にマージされる。Auto-mergeのボタンは、レビューやStatus Checkなどの条件が未達で、すぐにはマージできないPRに表示される。

    特に次のようなPRと相性がよい。

    • 軽微なバグ修正

    • ドキュメント更新

    • Dependabotによる依存関係更新

    • レビュー済みで、CIの完了だけを待っているPR

    また、GitHub Copilotのレビューなどを組み込むとコード品質は上がるだろう。
    ただし、本番環境への影響が大きい変更では、最終確認を手動で行う運用も検討されたし。

    3. 新しいコミットが来たら古いCIを停止する

    PRへ短時間に何度もコミットを追加すると、すでに古くなったコミットに対するCIが動き続けることがある。
    次の設定をワークフローへ追加すると、同じブランチで新しいCIが開始されたときに、古い実行を自動キャンセルできる。

    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
      cancel-in-progress: true

    たとえば、次のようなワークフローで利用できる。

    name: CI
    
    on:
      pull_request:
    
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
      cancel-in-progress: true
    
    jobs:
      test:
        runs-on: ubuntu-latest
    
        steps:
          - uses: actions/checkout@v4
    
          - run: npm ci
    
          - run: npm test

    `github.workflow`をグループ名に含めることで、別のワークフローまで誤ってキャンセルするのを防ぎやすくなる。

    同じConcurrency Groupでは、同時に実行されるワークフローまたはジョブが制限され、`cancel-in-progress: true`を指定すると進行中の古い実行がキャンセルされる。

    ただし、デプロイ処理では注意が必要だ。
    CIでは「古いコミットのテスト結果は不要」と判断できるが、デプロイを途中でキャンセルすると環境が中途半端な状態になる可能性がある。
    まずはPRのテストやLintから導入するのが安全だろう。

    4. 変更されたファイルに応じてCIを実行する

    ドキュメントしか変更していないのに、アプリケーションのビルドやE2Eテストまで実行されていないだろうか。

    `paths`または`paths-ignore`を使うと、変更されたファイルに応じてワークフローの実行を制御できます。

    特定のディレクトリが変更されたときだけ実行する

    on:
      pull_request:
        paths:
          - "apps/web/**"
          - "packages/**"
          - "package.json"
          - "package-lock.json"

    ドキュメントだけの変更では実行しない

    on:
      pull_request:
        paths-ignore:
          - "docs/**"
          - "**/*.md"

    モノレポでは、フロントエンドとバックエンドのCIを分離すると効果的だ。

    # frontend-ci.yml
    on:
      pull_request:
        paths:
          - "frontend/**"
    # backend-ci.yml
    on:
      pull_request:
        paths:
          - "backend/**"

    これにより、変更と関係のないテストを減らし、CI時間と実行コストを抑えられる。

    ただし、Path Filterによってワークフロー自体がスキップされた場合、そのワークフローのチェックが`Pending`のまま残り、必須チェックに指定しているPRがマージできなくなる場合がある。Rulesetや必須Status Checkとの組み合わせは、実際のPRで確認してから導入されたし。

    5. CIにタイムアウトを設定する

    テストコードやシェルスクリプトが終了せず、GitHub Actionsが長時間動き続けることがある。
    各ジョブに`timeout-minutes`を設定しておくと、想定以上に長い実行を自動停止できる。

    jobs:
      test:
        runs-on: ubuntu-latest
        timeout-minutes: 15
    
        steps:
          - uses: actions/checkout@v4
    
          - run: npm ci
    
          - run: npm test

    テストが通常3分程度で終わるなら、10分から15分程度のタイムアウトを設定しておくとよいだろう。
    GitHub Actionsのジョブは、`timeout-minutes`を指定しない場合、デフォルトで最大360分実行される。処理のハングを早く検知するためにも、プロジェクトに合った値を明示することをおすすめする。

    6. `GITHUB_TOKEN`の権限を最小化する

    GitHub Actionsでは、ワークフローからGitHub APIなどへアクセスするために`GITHUB_TOKEN`が利用される。
    特に書き込み権限が不要なCIでは、権限を明示的に読み取り専用へ制限されたし。

    permissions:
      contents: read

    ワークフロー全体へ適用する一例は以下のよう。

    name: CI
    
    on:
      pull_request:
    
    permissions:
      contents: read
    
    jobs:
      test:
        runs-on: ubuntu-latest
    
        steps:
          - uses: actions/checkout@v4
    
          - run: npm ci
    
          - run: npm test

    PRへのコメント投稿など、特定のジョブだけ書き込み権限が必要な場合は、ジョブ単位で追加できる。

    jobs:
      comment:
        permissions:
          contents: read
          pull-requests: write

    `permissions`で一部の権限を指定すると、明示していない権限は`none`となる。必要な権限だけを付与することで、ワークフローや利用しているActionに問題があった場合の影響を小さくできる。


    7. パッケージキャッシュを数行で有効にする

    Node.jsプロジェクトでは、`actions/setup-node`へ`cache`を指定するだけで、npm、Yarn、pnpmの依存関係キャッシュを利用できる。
    npmを使用する一例。

    steps:
      - uses: actions/checkout@v4
    
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
    
      - run: npm ci
    
      - run: npm test

    モノレポなど、Lock Fileがルート以外にある場合は`cache-dependency-path`も指定する。

    - uses: actions/setup-node@v4
      with:
        node-version: 22
        cache: npm
        cache-dependency-path: frontend/package-lock.json

    毎回すべてのパッケージをダウンロードする必要がなくなるため、CI時間を短縮しやすくなる。
    GitHubでは、npm、Yarn、pnpmのキャッシュに`setup-node`を利用でき、依存関係キャッシュを少ない設定で作成・復元できる。

    なお、キャッシュされるのは基本的にパッケージマネージャーのダウンロードキャッシュだ。`node_modules`をそのまま保存する設定とは異なる。

    8. PRテンプレートで説明の抜け漏れを減らす

    PRごとに説明の粒度が異なると、レビュアーは毎回次のような確認をすることになる。

    • 何を変更したのか

    • なぜ変更したのか

    • どのように確認したのか

    • 影響範囲はどこか

    `.github/pull_request_template.md`を作成すると、新しいPRの本文へテンプレートが自動挿入される。

    ## 概要
    
    <!-- このPRで変更した内容を記載してください -->
    
    ## 変更理由
    
    <!-- なぜこの変更が必要なのかを記載してください -->
    
    ## 動作確認
    
    - [ ] ローカル環境で確認した
    - [ ] 関連するテストを実行した
    - [ ] 既存機能への影響を確認した
    
    ## 影響範囲
    
    <!-- 影響する画面、API、バッチなどを記載してください -->
    
    ## 関連Issue
    
    Closes #

    PRテンプレートは、リポジトリのルート、`docs`ディレクトリ、または`.github`ディレクトリに配置できる。
    複数のテンプレートを使い分ける構成も可能。

    項目を増やしすぎると、テンプレートを埋めること自体が目的になってしまうため、
    最初は次の4項目程度で十分だろう。

    概要
    変更理由
    動作確認
    影響範囲

    9. CODEOWNERSでレビュアーを自動指定する

    フロントエンドの変更はフロントエンドチーム、インフラの変更は基盤チームにレビューしてほしい。
    このような場合は、`CODEOWNERS`を利用できる。

    `.github/CODEOWNERS`を作成する。

    # デフォルトのレビュアー
    * @example-org/development-team
    
    # フロントエンド
    /frontend/ @example-org/frontend-team
    
    # バックエンド
    /backend/ @example-org/backend-team
    
    # GitHub Actionsやリポジトリ設定
    /.github/ @example-org/platform-team
    
    # セキュリティ関連
    /SECURITY.md @example-org/security-team

    対象ファイルを変更したPRが作成されると、対応するCode Ownerへ自動的にレビューがリクエストされる。
    さらに、RulesetやBranch Protectionと組み合わせれば、Code Ownerの承認をマージ条件にできる。
    ただし、Code Ownerに指定するユーザーやチームには、対象リポジトリへの書き込み権限が必要だ。
    チームを指定する場合は、そのチームが可視状態である必要がある。

    すべてのファイルを細かく分類する必要はない。
    最初は次のような、影響が大きい領域だけでも十分だ。

    /.github/
    /infra/
    /database/
    /SECURITY.md

    10. DependabotのPRをまとめる

    Dependabotを有効にしたものの、大量のPRが作られ、確認しきれなくなった経験はないだろうか。

    `.github/dependabot.yml`の`groups`を利用すると、複数の依存関係更新を一つのPRへまとめられる。
    次の例では、npmパッケージのMinor UpdateとPatch Updateを、週に一つのPRへまとめる。

    version: 2
    
    updates:
      - package-ecosystem: npm
        directory: /
        schedule:
          interval: weekly
    
        groups:
          minor-and-patch:
            applies-to: version-updates
            patterns:
              - "*"
            update-types:
              - minor
              - patch

    Major Updateはグループに含まれないため、個別のPRとして作成される。
    これにより、次のような運用ができる。

    Minor・Patch Update
      → まとめて確認
      → CI通過
      → Auto-merge
    
    Major Update
      → 個別に影響を確認
      → 手動でマージ

    Dependabotでは、パッケージの種類、依存関係名、依存関係の用途、SemVerの更新レベルなどを条件にグループを作成できる。
    依存関係の更新PRをまとめるとCIの実行回数も減らせますが、一つのPRへ変更を詰め込みすぎると、問題が起きたパッケージを特定しづらくなる。
    まずはMinor・Patch Updateのみをまとめる構成がおすすめだ。

    おまけ:Actions一覧を`run-name`で読みやすくする

    GitHub Actionsの一覧に似た名前の実行が並び、どのブランチや実行者によるものか分かりにくい場合があります。

    `run-name`を設定すると、Actions画面に表示される実行名を変更できる。

    name: CI
    
    run-name: CI / ${{ github.ref_name }} / ${{ github.actor }}
    
    on:
      pull_request:
      workflow_dispatch:

    `run-name`では、`github`や`inputs`などのContextを参照できる。

    小さな設定ですが、失敗したワークフローを一覧から探しやすくなる。

    最初に導入するならこの5つ

    すべてを一度に導入する必要はない。
    まずは、設定が簡単で副作用も比較的小さい次の5つから始めるとよいだろう。

    1. マージ済みブランチの自動削除

    2. PRテンプレート

    3. CIの`timeout-minutes`

    4. CIの`concurrency`

    5. `GITHUB_TOKEN`の権限最小化

    その後、チームの課題に応じて次の機能を追加する。

    レビュー担当が分かりにくい
      → CODEOWNERS
    
    CIの実行時間が長い
      → キャッシュ、Path Filter
    
    CI待ちでマージを忘れる
      → Auto-merge
    
    DependabotのPRが多すぎる
      → Dependabot Groups

    まとめ

    GitHubを使った開発体験の改善というと、大規模なCI/CDパイプラインや高度な自動化を想像しがちだ。

    しかし実際には、次のような小さな改善でも十分な効果がある。

    • 不要な操作を一つ減らす

    • 待ち時間を一つ減らす

    • レビュー時の確認を一つ減らす

    • 無駄なCIを一つ減らす

    • 権限を一つ減らす

    一回あたり数十秒の削減でも、チーム全員が毎日繰り返せば大きな差となる。
    まずは、現在チーム内で手動対応している作業や、毎回面倒に感じている操作を一つ探されたし。
    それは、GitHubの設定を一つ変更するだけで解決できる問題かもしれない。

     
     

    KOKAGE

     
     
    2025年3月大阪大学理学部化学科卒業 学部時代に独学でプログラミングを趣味としており、その楽しさに目覚める 2025年4月よりWebエンジニアとして働き始めた若手プログラマ

    あなたへのおすすめ