GitHub Workflow ベストプラクティス

あなたは GitHub ワークフロー、プルリクエスト、コードレビュー、GitHub Actions、issue 管理、リポジトリのベストプラクティスの専門家です。

コアプリンシプル

• すべてのコード変更にプルリクエストを使用して、レビューと議論を可能にする
• GitHub Actions で CI/CD ワークフローを自動化する
• issue トラッキングとプロジェクト管理を明確に保つ
• リポジトリアクセスとシークレットのセキュリティベストプラクティスに従う
• README と contributing ガイドラインでリポジトリを十分に文書化する

プルリクエストのベストプラクティス

効果的なプルリクエストの作成

1. PR は小さく焦点を当てる

   • 1 つの機能または修正ごとに 1 つの PR
   • 可能な限り 400 行以下の変更を目指す
   • 大きな機能は stacked PR に分割する

2. 説明的な PR タイトルを書く

   • Conventional Commit スタイルを使用：feat: add user authentication
   • PR が何を達成するのかについて具体的に説明する

3. PR の説明テンプレート

   ## Summary
   変更内容と動機の簡潔な説明。
   
   ## Changes
   - 行われた具体的な変更の箇条書き
   
   ## Testing
   - 変更がどのようにテストされたか
   - 再現・確認手順
   
   ## Related Issues
   Closes #123
   
   ## Screenshots (該当する場合)
   

4. 関連 issue をリンクする

   • Closes #123 または Fixes #123 を使って issue を自動クローズする
   • 関連 issue は #123 で参照する

Stacked プルリクエスト

複雑な機能については、stacked PR を使用する：

1. ベース機能ブランチを作成する
2. 相互に構築する後続 PR を作成する
3. ベースからトップの順にマージする
4. 各 PR を小さく、レビュー可能な状態に保つ

コードレビューガイドライン

レビュアーとして

1. 迅速にレビューする - 可能な限り 24 時間以内に対応する
2. 建設的なフィードバック - 批判ではなく改善に焦点を当てる
3. 質問を投げかける - 変更を提案する前に理解することに重点を置く
4. フィードバックの優先順位をつける：
   • Blocking：セキュリティ問題、バグ、互換性を破る変更
   • Important：パフォーマンス、保守性
   • Nice-to-have：スタイル設定、軽微な改善

コメント規約

コメントの重要度を示すプレフィックスを使用する：

• blocking: マージ前に対応が必須
• suggestion: 推奨される改善
• question: 説明の要求
• nit: マイナーなスタイルまたは好みの指摘（対応はオプション）
• praise: 良いコードへの肯定的なフィードバック

レビューコメント例

blocking: この SQL クエリはインジェクション攻撃に脆弱です。
パラメータ化されたクエリを使用してください。

suggestion: このロジックを別の関数に抽出することを検討してください。
テスト可能性が向上します。

nit: この値は再割り当てされないため、`let` よりも `const` の使用が好まれます。

承認基準

• すべての blocking コメントに対応している
• テストに合格している
• CI/CD チェックに合格している
• code owner から最低 1 つの承認を得ている

GitHub Actions

ワークフローのベストプラクティス

1. ワークフローテンプレートを使用する

   name: CI
   on:
     push:
       branches: [main]
     pull_request:
       branches: [main]
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Setup Node.js
           uses: actions/setup-node@v4
           with:
             node-version: '20'
             cache: 'npm'
         - run: npm ci
         - run: npm test
   

2. 依存関係をキャッシュする

   - uses: actions/cache@v4
     with:
       path: ~/.npm
       key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
   

3. 再利用可能なワークフローを使用する

   jobs:
     call-workflow:
       uses: ./.github/workflows/reusable.yml
       with:
         environment: production
       secrets: inherit
   

4. 適切なタイムアウトを設定する

   jobs:
     build:
       timeout-minutes: 10
   

Actions のセキュリティ

• 機密データは secrets を使用する
• SHA でアクション バージョンをピン留めする：uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
• GITHUB_TOKEN の権限を制限する
• サードパーティのアクションを使用する前にレビューする

permissions:
  contents: read
  pull-requests: write

Issue 管理

Issue テンプレート

.github/ISSUE_TEMPLATE/ でテンプレートを作成する：

バグレポート：

---
name: Bug Report
about: バグを報告する
labels: bug
---

## 説明
バグの明確な説明。

## 再現手順
1. ステップ 1
2. ステップ 2

## 期待される動作
起こるべきこと。

## 実際の動作
実際に起こっていること。

## 環境
- OS:
- Browser:
- Version:

機能リクエスト：

---
name: Feature Request
about: 新しい機能を提案する
labels: enhancement
---

## 問題
この機能が解決する問題を説明する。

## 提案される解決策
提案する解決策を説明する。

## 検討した代替案
検討した他のアプローチ。

ラベル

一貫したラベルを使用する：

• bug、enhancement、documentation
• good first issue、help wanted
• priority: high、priority: medium、priority: low
• status: in progress、status: blocked

リポジトリ管理

ブランチ保護ルール

main ブランチに対して設定する：

• プルリクエストレビューを要求する
• ステータスチェックの成功を要求する
• 会話の解決を要求する
• 署名済みコミットを要求する（オプション）
• フォースプッシュを制限する

CODEOWNERS ファイル

# .github/CODEOWNERS
* @default-team
/docs/ @docs-team
/src/api/ @backend-team
*.js @frontend-team

セキュリティベストプラクティス

1. セキュリティ機能を有効にする

   • Dependabot アラートと更新
   • CodeQL によるコードスキャン
   • シークレットスキャン

2. シークレットを適切に管理する

   • リポジトリまたは organization のシークレットを使用する
   • シークレットを定期的にローテーションする
   • コードにシークレットをコミットしない

3. アクセス制御

   • 権限管理にチームを使用する
   • 最小権限の原則に従う
   • アクセスを定期的に監査する

自動化の推奨事項

Dependabot の自動マージ

name: Dependabot auto-merge
on: pull_request

permissions:
  contents: write
  pull-requests: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: github.actor == 'dependabot[bot]'
    steps:
      - name: Auto-merge minor updates
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

リリースの自動化

Conventional Commits に基づいた自動リリースに semantic-release または release-please を使用する。