github-workflow

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

プルリクエスト、コードレビュー、GitHub Actions、Issue 管理、リポジトリのベストプラクティスなど、GitHub ワークフローに精通しています。

基本原則

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

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

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

1. PR は小さく、目的を絞ります

   • 1 つの PR につき 1 つの機能または修正にします
   • 可能な場合、変更行数を 400 行未満にすることを目指します
   • 大規模な機能は複数の積み重ねた PR に分割します

2. 内容がわかる PR タイトルを付けます

   • feat: add user authentication のように、Conventional Commits の形式を使用します
   • PR で何を実現するのかを具体的に記述します

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

   ## Summary
   Brief description of changes and motivation.
   
   ## Changes
   - Bullet points of specific changes made
   
   ## Testing
   - How the changes were tested
   - Steps to reproduce/verify
   
   ## Related Issues
   Closes #123
   
   ## Screenshots (if applicable)
   

4. 関連する Issue をリンクします

   • Closes #123 または Fixes #123 を使用して、Issue を自動的にクローズします
   • #123 を使って関連する Issue を参照します

積み重ねたプルリクエスト

複雑な機能では、積み重ねた PR を使用します。

1. ベースとなる機能ブランチを作成します
2. それぞれをベースにして、後続の PR を作成します
3. ベースから先頭に向かって順番にマージします
4. 各 PR を小さく保ち、レビューしやすくします

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

レビュアーとして

1. 速やかにレビューします - 可能な場合、24 時間以内に返信します
2. 建設的に対応します - 批判ではなく、改善に焦点を当てます
3. 質問します - 変更を提案する前に、まず理解に努めます
4. フィードバックに優先順位を付けます：
   • ブロッキング：セキュリティ上の問題、バグ、互換性を損なう変更
   • 重要：パフォーマンス、保守性
   • あるとよいもの：スタイルの好み、軽微な改善

コメントの規則

コメントの重要度を示す接頭辞を使用します。

• blocking: マージ前に対応が必要です
• suggestion: 推奨する改善です
• question: 説明を求めています
• nit: 軽微なスタイルや好みの指摘です（対応は任意）
• praise: 良いコードに対する肯定的なフィードバックです

レビューコメントの例

blocking: This SQL query is vulnerable to injection.
Please use parameterized queries.

suggestion: Consider extracting this logic into a separate
function for better testability.

nit: Prefer `const` over `let` here since this value
is never reassigned.

承認条件

• ブロッキングコメントがすべて対応済みであること
• テストが成功すること
• CI/CD チェックが成功すること
• コードオーナーから少なくとも 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: Report a bug
labels: bug
---

## Description
Clear description of the bug.

## Steps to Reproduce
1. Step one
2. Step two

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS:
- Browser:
- Version:

機能リクエスト：

---
name: Feature Request
about: Suggest a new feature
labels: enhancement
---

## Problem
Describe the problem this feature would solve.

## Proposed Solution
Describe your proposed solution.

## Alternatives Considered
Other approaches you've considered.

ラベル

一貫性のあるラベルを使用します。

• 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. シークレットを適切に管理します

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

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 を使用します。