ワイのGitHubリポジトリおすすめ設定(2022年 決定版)

はじめに

はじめまして、「拳で」 と申します。
NRI OpenStandia Advent Calendar 2022の13日目は ワイのGitHubリポジトリおすすめ設定(2022年 決定版) というタイトルでお送りいたします!

2022年も終わりが近づき、「年末年始に何か開発でもしてみようかな？」と思っている方も多いのではないでしょうか。
新しくGitHubリポジトリを作成する際に、 「拳で」 がおすすめするぜひ入れてほしい設定 を色々と紹介させていただきました!

開発用途などでフィットする設定は変わってくるかと思いますが、参考までにご覧いただければ幸いです
また、皆様のおすすめの設定がございましたらぜひコメントで教えていただけると大変喜びます🙇‍♂️

補足
記事内で特に説明の無い設定項目はデフォルト設定のままとなります。

TL;DR

• 設定チートシートを見てね!
• 各テンプレートはjonghyo/astro-docs-template　←　ここに入れてるので見てね!

前提条件

今回は以下のような用途、条件のリポジトリを想定しています。

項目	条件
人数	個人・少人数
開発目的	プライベート開発
開発内容	Webアプリ開発
リポジトリ種別	Public
ブランチ戦略	GitHub-flow
バージョニング	セマンティックバージョニング
方針	GitHub無料枠で使える機能を活用する

設定対象

今回紹介する設定対象は以下2つです。

1. Repository Settings
2. Repository Templates

1. Repository Settings

おすすめの設定内容をシートにまとめました💡
よろしければ、ご活用ください🙇‍♂️
各設定の選定理由をこの章で紹介します。

設定チートシート

1.1 General

1.1.1 General

Require contributors to sign off on web-based commits

必要に応じて有効

機能について
GitHubのWeb上で編集を行う場合、コミット時にサインオフを求める機能です。
詳細はリポジトリの強制コミット サインオフを有効または無効にする
をご覧ください。

推奨シーン

• OSS開発など様々な開発者のコミットが想定されるとき

理由

• OSS開発などにおいて、コミッターの方に著作権やライセンスなどの条件に賛同した上で署名してもらうため
• ただし、GitHubのWeb上からの設定しか効果がないです😇
• プライベート開発だと、ここまでガチることもないので無効のケースが多いです

1.1.2 Features

Discussions

有効

機能について

GitHub上で課題などについて、メンバと議論するための機能です。GitHub公式では以下のような使い分けを推奨しています。

• GitHub Discussions： 仕様や処理方式などの議論、方針決め
• GitHub Issues: 方針決定後の作業の管理・分類

詳細はWhat is GitHub Discussions? A complete guideをご覧ください。

推奨シーン

• チームメンバと処理方式などを議論する用

理由

• GitHubが推奨する使い方に則って、「議論 → GitHub Discussions」「作業 → GitHub Issues」とすることで着手可能な作業が何なのか管理しやすいようにするため

1.1.3 Pull Requests

Allow rebase merging

無効

機能について

Pull Requestのマージ時に、Rebase and mergeが選択できます。これを行うと、merge commitではなくrebaseされます。

GithubでのWeb上からのマージの仕方3種とその使いどころの記事がわかりやすいです。

推奨シーン

• 全シーン

理由

• ブランチの分岐や何をマージしたか記録を残したいため

Always suggest updating pull request branches

有効

機能について

Pull Request作成後に、ベースブランチが更新された場合、ソースブランチの更新を提案してくれるようになります。

コピペで学ぶチュートリアル: GitHub Pull Request の update手法2種類を試すの記事がわかりやすいです。

推奨シーン

• 全シーン

理由

• Pull Request作成後にブランチに更新があった場合、簡単にupdateできるようにするため

Automatically delete head branches

有効

機能について
Pull Requestをマージすると、ソースブランチを自動的に削除するようになります。

推奨シーン

• 全シーン

理由

• マージ済みの不要になったブランチを手動で削除するのが面倒なので

1.1.4 Pushes

Limit how many branches and tags can be updated in a single push

有効

機能について
複数のブランチが一度のpushでまとめて更新される場合、ブロックする機能です。

推奨シーン

• 全シーン

理由

• git push origin –mirrorなどで誤ってリモートリポジトリを破壊しないため。詳細はBlock potentially destructive Git pushesが参考になります。

1.2 Access

1.2.1 Moderation options

Code review limits

有効

機能について
Pull Requestの「承認」「変更要求」を明示的に許可したユーザだけが行えるようになります。

推奨シーン

• 全シーン

理由

• Publicリポジトリで開発する際に、意図しないユーザによるPull Requestの承認が行われないようにするため

1.3 Branches

1.3.1 Default branch

main

機能について
リポジトリのデフォルトブランチを指定する機能です。

推奨シーン

• 全シーン

理由

• 深い理由なし。昨今一般的な、mainをデフォルトブランチとする。

1.3.2 Branch protection rules

Branch name pattern

main

Require a pull request before merging

有効

その他以下のような設定を使ってます。

※Require branches to be up to data before mergingは適宜、自分が定義したCIパイプラインのワークフロー名などを指定してください。

機能について
指定したブランチへマージする際のルールを設定できます。

推奨シーン

• 全シーン

理由

• デフォルトブランチへのマージは、変更内容をレビューするためPull Requestを必須としたい。
• レビュー承認を必須とすることで、未レビューのコードがマージされることを避けたい。
• レビュー承認後にコードに変更があった場合、再度レビューを行いたい。
• CIパイプラインの実行結果もマージ条件としたい。
• レビュー指摘に全て対応完了してから、マージしたい。

1.4 Tags

1.4.1 Protected tags

[0-9].[0-9].[0-9]

機能について
指定した正規表現にマッチするタグの削除を抑止します。

推奨シーン

• 全シーン

理由

• セマンティックバージョニングに従ってつけたタグを保護するため

1.5 Actions

1.5.1 General

Actions permissions

Allow OWNER, and select non-OWNER, actions and reusable workflows

• Allow actions created by GtiHub: 有効
• Allow actions by Marketplace verified creators: 有効

機能について
指定したルールに基づいて、GitHub Actionsのworkflowの実行を許可します。

推奨シーン

• 全シーン

理由

• 悪意のあるworkflowなどが混入しないようにするため。
• 基本的にプロジェクトで必要なworkflowは作成するため、認証済みのworkflowのみ使えれば基本OK。

1.6 Codespaces

1.6.1 Prebuilds

Access and cost control

以下のように設定しています。

機能について
Visual Studio Code/実行基盤をブラウザから利用できるCodespacesのdevcontainerを高速起動するため、事前にビルドするための設定を行います。

推奨シーン

• 全シーン

理由

• On configuration changeとすることでprebuildの実行を最小限とする
  • GitHub Actionsで実行されるため、prebuildしすぎるとGitHub Actionsの実行時間無償枠が減ってしまう。
    • 参考：プレビルドの構成
  • devcontainer内のライブラリなどは更新されないため、定義自分で更新する。
• Reduce prebuild available to only specific regionsを有効化することで、よく使うリージョン以外にdevcontainerが生成されストレージを食うことを抑止する
  • 無料枠はストレージ15GB/月となっている。　
    • 参考： 個人用アカウントに含まれる月間ストレージとコア時間

1.7 Security

1.7.1 Code security and analysis

Dependabot

• Dependabot alerts: 有効
• Dependabot security updates: 有効
• Dependabot version updates: 有効

機能について

Dependabotを用いて、依存ライブラリの脆弱性チェックなどが実施できるようになります。

推奨シーン

• 全シーン

理由

• 依存ライブラリの脆弱性チェックやセキュリティアップデート・バージョンアップを自動検知できるようにするため。

Code scanning

有効

機能について
GitHub Actionsのworkflowでソースコードの静的解析を行います。

推奨シーン

• 全シーン

理由

• ソースコードの静的解析を実施し、コードの品質を高めるため

1.7.2 Secrets

Actions

• ACTIONS_RUNNER_DEBUG: true
• ACTIONS_STEP_DEBUG: true

機能について
上記環境変数を定義することで、GitHub Actionsのworkflowログがデバッグログレベルまで確認できるようになります。

推奨シーン

• 全シーン

理由

• GitHub Actionsのworkflowログは標準では、大した情報量がないためworkflowが失敗したときに原因を把握できるようにするため
  • 参考： [GitHub]Actionsの動作確認時は忘れずにACTIONS_RUNNER_DEBUGとACTIONS_STEP_DEBUGを設定しよう

2. Repository Templates

以下2つのテンプレートについて紹介します。

• GitHub Issue Template
• GitHub Actions

2.1 GitHub Issue Template

リポジトリの Settings > General > Features > Issues > Set up templates をクリックします。
ワイはcodeforamerica/howtoを参考にIssueテンプレートを作ってます。

feature_request.md

#### Description
A clear and concise description of what the issue is about.

#### Screenshots
![Downhill Windmills](http://i.giphy.com/KO8AG2EByqkFi.gif)

#### Files
A list of relevant files for this issue. This will help people navigate the project and offer some clues of where to start.

#### To Reproduce
If this issue is describing a bug, include some steps to reproduce the behavior.

#### Tasks
Include specific tasks in the order they need to be done in. Include links to specific lines of code where the task should happen at.
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

Remember to use helpful labels and milestones. If you use the "help wanted" label, Code for America will [promote it widely](http://www.codeforamerica.org/geeks/civicissues).

他にもdevspace/awesome-github-templatesに参考になるテンプレートが色々あります

2.2 GitHub Actions

Dependabot version updates

リポジトリの Settings > Security > Code security and analysis > Dependabot version updates > Set up templates をクリックします。

以下のような定義を作成します。
※利用するpackage-ecosystemやディレクトリ構成に応じて都度調整ください

dependabot.yml

# To get started with Dependabot version updates, you'll need to specify which
# package ecosystems to update and where the package manifests are located.
# Please see the documentation for all configuration options:
# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily" #インターバルや実行時間帯はお好みで
      time: "06:00"
      timezone: "Japan"
    commit-message:
      prefix: "Common"
      include: "scope"
    labels:
      - "dependencies"  #ラベルは適宜選択・作成する
  - package-ecosystem: "npm"
    directory: "src/"   #Dependabotはリポジトリ全体を再帰的にチェックしてくれないので、検査対象のディレクトリを都度指定する
    schedule:
      interval: "daily"
      time: "06:00"
      timezone: "Japan"
    commit-message:
      prefix: "Frontend"
      include: "scope"
    labels:
      - "dependencies"

パッチバージョンの自動マージ

Dependabotにバージョンアップチェックをしてもらうようになると、上図のようにPull Requestがどんどん溜まっていくのでパッチバージョンのバージョンアップPull Requestの自動マージを導入します。

注意
パッチバージョンであっても自動マージはバグや障害の原因の1つになり得るので、自動テストなどとセットで導入をおすすめします。自動マージの導入はメリット・デメリットを把握した上でご検討ください。

リポジトリルート直下の.github/workflows配下に自動マージのworkflowを作成します。

dependabot-auto-merge.yml

ame: Dependabot auto-merge
on: pull_request_target

permissions:
  pull-requests: write
  contents: write

jobs:
  dependabot:
    runs-on: ubuntu-22.04
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - name: Dependabot metadata
        id: metadata
        uses: dependabot/fetch-metadata@v1.3.5
        with:
          github-token: '${{ secrets.GITHUB_TOKEN }}'
      - name: Enable auto-merge for Dependabot PRs
        if: ${{ steps.metadata.outputs.update-type == 'version-update:semver-patch' }}
        run: gh pr merge --auto --merge "$PR_URL"
        env:
          PR_URL: ${{github.event.pull_request.html_url}}
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

以下記事が参考になります。

Code scanning

リポジトリの Settings > Security > Code security and analysis > Code scanning > Set up をクリックします。

様々なworkflowが選択できますが、ワイはGitHub公式が提供する CodeQL Analysis を利用しています。

生成されたworkflowを適宜修正してpushします。

codeql.yml

codeql.yml

# For most projects, this workflow file will not need changing; you simply need
# to commit it to your repository.
#
# You may wish to alter this file to override the set of languages analyzed,
# or to provide custom queries or build logic.
#
# ******** NOTE ********
# We have attempted to detect the languages in your repository. Please check
# the `language` matrix defined below to confirm you have the correct set of
# supported CodeQL languages.
#
name: "CodeQL"

on:
  push:
    branches: [ "main" ]　　#適宜実行タイミングを変更
  pull_request:
    # The branches below must be a subset of the branches above
    branches: [ "main" ]
  schedule:
    - cron: '22 7 * * 2'  #適宜実行頻度・時間帯を変更

jobs:
  analyze:
    name: Analyze
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: [ 'javascript' ] #適宜言語を変更
        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v2
      with:
        languages: ${{ matrix.language }}
        # If you wish to specify custom queries, you can do so here or in a config file.
        # By default, queries listed here will override any specified in a config file.
        # Prefix the list here with "+" to use these queries and those in the config file.

        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
        # queries: security-extended,security-and-quality


    # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
    # If this step fails, then you should remove it and run the build manually (see below)
    - name: Autobuild
      uses: github/codeql-action/autobuild@v2

    # ℹ️ Command-line programs to run using the OS shell.
    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun

    #   If the Autobuild fails above, remove it and uncomment the following three lines.
    #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.

    # - run: |
    #   echo "Run, Build Application using script"
    #   ./location_of_script_within_repo/buildscript.sh

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v2
      with:
        category: "/language:${{matrix.language}}"

まとめ

おすすめのGitHubリポジトリ設定を紹介させていただきました!
この機会にGitHubリポジトリの設定を見直して快適な開発ライフを過ごしましょう

GitHub Docs -REST API- Repositories
いずれ、APIを使って簡単にリポジトリ設定ができるように整備したい...