github-project-automation

GitHub プロジェクトの自動化

ステータス: 本番環境対応済み ✅ 最終更新日: 2025-12-17 バージョン: 2.0.0（段階的な情報開示により最適化） 依存関係: なし（git と gh CLI を推奨） 最新バージョン: actions/[email protected]、actions/[email protected]、github/[email protected]

---

クイックスタート（15 分）

1. フレームワークを選択する

プロジェクトに合ったワークフローテンプレートを選択します。

# For React/Vite projects
cp templates/workflows/ci-react.yml .github/workflows/ci.yml

# For Node.js libraries (matrix testing)
cp templates/workflows/ci-node.yml .github/workflows/ci.yml

# For Python projects
cp templates/workflows/ci-python.yml .github/workflows/ci.yml

# For Cloudflare Workers
cp templates/workflows/ci-cloudflare-workers.yml .github/workflows/deploy.yml

# For basic projects (any framework)
cp templates/workflows/ci-basic.yml .github/workflows/ci.yml

重要な理由:

• 事前検証済みの YAML により構文エラーを防止
• セキュリティのため、アクションを SHA で固定
• ランナーのバージョンを明示（ubuntu-24.04）
• GitHub Actions の 8 つのエラーをすべて防止

2. イシューテンプレートを追加する

# Create directory structure
mkdir -p .github/ISSUE_TEMPLATE

# Copy YAML templates (with validation)
cp templates/issue-templates/bug_report.yml .github/ISSUE_TEMPLATE/
cp templates/issue-templates/feature_request.yml .github/ISSUE_TEMPLATE/

Markdown より YAML が優れている理由:

• 必須フィールドの検証（エラー #12 を防止）
• 一貫したデータ構造
• 優れたユーザーエクスペリエンス
• 不完全なイシューの作成を防止

3. セキュリティスキャンを有効にする

# CodeQL for code analysis
cp templates/workflows/security-codeql.yml .github/workflows/codeql.yml

# Dependabot for dependency updates
cp templates/security/dependabot.yml .github/dependabot.yml

重要:

• CodeQL には特定の権限（security-events: write）が必要
• Dependabot の PR 上限はエコシステムごとに 10 件
• どちらも Dependabot の PR で実行する必要があります（エラー #13 を防止）

---

5 ステップで完了するセットアップ手順

ステップ 1: リポジトリの構成

標準的な GitHub 自動化ディレクトリ構成を作成します。

# Create all required directories
mkdir -p .github/{workflows,ISSUE_TEMPLATE}

# Verify structure
tree .github/
# .github/
# ├── workflows/        # GitHub Actions workflows
# ├── ISSUE_TEMPLATE/   # Issue templates
# └── dependabot.yml    # Dependabot config (root of .github/)

要点:

• workflows/ は複数形
• ISSUE_TEMPLATE/ は単数形（従来の命名規則）
• dependabot.yml は .github/ に配置し、workflows/ には配置しない

ステップ 2: ワークフローテンプレートを選択する

プロジェクトのニーズに応じてワークフローを選択します。

継続的インテグレーション（1 つ選択）:

1. ci-basic.yml - 汎用的なテスト／lint／ビルド（すべてのフレームワーク）
2. ci-node.yml - マトリックステストに対応した Node.js（18、20、22）
3. ci-python.yml - マトリックステストに対応した Python（3.10、3.11、3.12）
4. ci-react.yml - 型チェックに対応した React／TypeScript

デプロイ（任意）: 5. ci-cloudflare-workers.yml - Cloudflare Workers にデプロイ

セキュリティ（推奨）: 6. security-codeql.yml - コードスキャン 7. dependabot.yml - 依存関係の更新

選択したテンプレートをコピーします。

# Example: React app with security
cp templates/workflows/ci-react.yml .github/workflows/ci.yml
cp templates/workflows/security-codeql.yml .github/workflows/codeql.yml
cp templates/security/dependabot.yml .github/dependabot.yml

ステップ 3: シークレットを設定する（デプロイする場合）

デプロイワークフロー（Cloudflare、AWS など）では、シークレットを追加します。

# Using gh CLI
gh secret set CLOUDFLARE_API_TOKEN
# Paste your token when prompted

# Verify
gh secret list

重要な構文:

# ✅ CORRECT
env:
  API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

# ❌ WRONG - Missing double braces
env:
  API_TOKEN: $secrets.CLOUDFLARE_API_TOKEN

エラー #6（シークレットの構文）を防止します。

ステップ 4: イシュー／PR テンプレートを追加する

イシューテンプレート（YAML 形式）:

cp templates/issue-templates/bug_report.yml .github/ISSUE_TEMPLATE/
cp templates/issue-templates/feature_request.yml .github/ISSUE_TEMPLATE/

PR テンプレート（Markdown 形式）:

cp templates/pr-templates/PULL_REQUEST_TEMPLATE.md .github/

形式を分ける理由:

• イシューテンプレート: 検証に対応する YAML
• PR テンプレート: Markdown（GitHub の制限）

ステップ 5: プロジェクトに合わせてカスタマイズする

必須のカスタマイズ:

1. ユーザー名／メールアドレスを更新する:

   # In issue templates
   assignees:
     - secondsky  # ← Change to your GitHub username
   
   # In dependabot.yml
   reviewers:
     - "secondsky"  # ← Change to your username
   

2. 言語を調整する（CodeQL）:

   # In security-codeql.yml
   matrix:
     language: ['javascript-typescript']  # ← Add your languages
     # Options: c-cpp, csharp, go, java-kotlin, python, ruby, swift
   

3. パッケージマネージャーを更新する（Dependabot）:

   # In dependabot.yml
   - package-ecosystem: "npm"  # ← Change if using yarn/pnpm/pip/etc
   

4. デプロイ URL を設定する（Cloudflare）:

   # In ci-cloudflare-workers.yml
   echo "Worker URL: https://your-worker.your-subdomain.workers.dev"
   # ← Update with your actual Worker URL
   

---

重要なルール

必ず行うこと

✅ アクションは @latest ではなく SHA で固定する

# ✅ CORRECT
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

# ❌ WRONG
- uses: actions/checkout@latest

✅ ランナーのバージョンを明示する

# ✅ CORRECT
runs-on: ubuntu-24.04  # Locked to specific LTS

# ❌ RISKY
runs-on: ubuntu-latest  # Changes over time

✅ コンテキスト構文でシークレットを含める

# ✅ CORRECT
${{ secrets.API_TOKEN }}

# ❌ WRONG
$secrets.API_TOKEN

✅ コミット前に YAML を検証する

# Use yamllint or GitHub's workflow validator
yamllint .github/workflows/*.yml

✅ 最初にフィーチャーブランチでワークフローをテストする

git checkout -b test/github-actions
# Push and verify CI runs before merging to main

絶対に行わないこと

❌ アクションのバージョンに @latest を使用しない

• アクションの更新時に警告なしで動作しなくなる
• セキュリティリスク（未検証のバージョンが自動的に採用される）

❌ ワークフローにシークレットをハードコードしない

# ❌ NEVER DO THIS
env:
  API_TOKEN: "sk_live_abc123..."  # Secret exposed in repo!

❌ コンパイル言語でビルド手順を省略しない（CodeQL）

# ❌ WRONG - CodeQL fails for Java without build
- name: Perform CodeQL Analysis  # No .class files to analyze

# ✅ CORRECT - Include build
- name: Build project
  run: ./mvnw clean install
- name: Perform CodeQL Analysis  # Now has .class files

❌ Dependabot で devDependencies を無視しない

• devDependencies はビルド時に実行され、悪意のあるコードを実行する可能性があります
• 本番用と開発用の依存関係の両方を含めてください

❌ 単一の ISSUE_TEMPLATE.md ファイルを使用しない

# ❌ OLD WAY
.github/ISSUE_TEMPLATE.md

# ✅ NEW WAY
.github/ISSUE_TEMPLATE/
  bug_report.yml
  feature_request.yml

---

既知の問題を防ぐ（重要度トップ 5）

このスキルは、記録されている 18 件の問題を防止します。特に重要な上位 5 件を紹介します。

問題 #1: YAML のインデントエラー ⚠️ 最も一般的

エラー: workflow file is invalid. mapping values are not allowed in this context 情報源: Stack Overflow（GitHub Actions で最も一般的なエラー） 発生理由: スペースとタブの混在、コロン後のスペース不足、不統一なインデント 防止策: 2 スペースのインデントを検証済みのスキルテンプレートを使用する 影響: ワークフローの解析に失敗し、CI が実行されない

Issue #2: アクションのバージョン固定に関する問題 🔒 SECURITY

エラー: アクションの更新後にワークフローが予期せず停止します ソース: GitHub Security Best Practices 2025 発生する理由: 特定の SHA ではなく、@latest または @v4 を使用しているため 防止策: すべてのテンプレートで、バージョンコメントを添えて SHA に固定しています 影響: 予期しない破壊的変更、セキュリティの脆弱性

Issue #3: シークレットを利用できない 🔑

エラー: Secret not found または変数が空になります ソース: GitHub Actions Debugging Guides 発生する理由: 構文が誤っているため（${{ secrets.NAME }} ではなく $secrets.NAME） 防止策: テンプレートで正しいコンテキスト構文を示しています 影響: デプロイの失敗、CI/CD パイプラインの停止

Issue #4: Dependabot の PR で CodeQL が実行されない 🛡️

エラー: 依存関係の更新時にセキュリティスキャンがスキップされます ソース: GitHub Community Discussion #121836 発生する理由: デフォルトのトリガーに制限があるため 防止策: テンプレートに push: branches: [dependabot/**] を含めています 影響: 脆弱な依存関係がスキャンされずにマージされます

Issue #5: Issue テンプレートに必須フィールドがない 📋

エラー: Issue の情報が不完全で、重要な情報が不足しています ソース: コミュニティからのフィードバック 発生する理由: Markdown テンプレートでは入力内容を検証できないため 防止策: required: true による検証を備えた YAML テンプレートを使用します 影響: バグを再現できず、トリアージに時間がかかります

18 件すべての問題を網羅したエラーの完全なドキュメントについて: GitHub Actions の問題をデバッグするときやワークフローを設定するときに、references/common-errors.md を読み込んでください。

---

参照資料を読み込むタイミング

GitHub オートメーションの特定の作業を行う際は、参照ファイルを読み込んでください。

よくあるエラー（references/common-errors.md）

次の場合に読み込みます：

• ワークフローの構文エラーが発生した
• 失敗した GitHub Actions の実行をデバッグする
• CodeQL または Dependabot を初めて設定する
• 「Secret not found」エラーを解決する
• マトリックスビルドが失敗する理由を確認する
• ドキュメントに記載された 18 件のエラーの詳細な解決方法が必要

ワークフローのパターン（references/workflow-patterns.md）

次の場合に読み込みます：

• 複数バージョンのテスト（Node.js 18/20/22）を実装する
• 条件付きデプロイ（main 対 PR）を設定する
• ジョブ間でビルド成果物を共有する
• GitHub オートメーションを他のスキル（cloudflare-worker-base、project-planning）と連携する
• ワークフローのパフォーマンスを最適化する
• マトリックス戦略や成果物のアップロード／ダウンロードの例が必要

設定例（references/configuration-examples.md）

次の場合に読み込みます：

• dependabot.yml を一から作成する
• 特定の言語向けに CodeQL を設定する
• GitHub Actions のシークレットを正しく設定する
• 完全に動作する設定ファイルが必要
• ブランチ保護ルールを確認する
• 適切な検証を備えた Issue／PR テンプレートを作成する

トラブルシューティングガイド（references/troubleshooting-guide.md）

次の場合に読み込みます：

• コードをプッシュしてもワークフローがトリガーされない
• CodeQL に「No code found to analyze」と表示される
• マトリックスビルドがすべて同じエラーで失敗する
• Dependabot の PR で CI が繰り返し失敗する
• 権限エラーが発生する（「Resource not accessible by integration」）
• 手順に沿ったデバッグ方法が必要

高度な設定（references/advanced-configurations.md）

次の場合に読み込みます：

• 複数環境へのデプロイ（ステージング／本番）を設定する
• 再利用可能なワークフローや複合アクションを作成する
• CI/CD パイプラインのパフォーマンスを最適化する
• 高度なマトリックス戦略を実装する
• クラウド認証に OIDC を使用する（長期間有効なシークレットを使わない）
• ワークフローの最適化手法が必要

---

既存のスキルとの連携

cloudflare-worker-base → CI/CD を追加

ユーザーが新しい Worker プロジェクトを作成する場合：

# User: "Create Cloudflare Worker with CI/CD"

# This skill runs AFTER cloudflare-worker-base
cp templates/workflows/ci-cloudflare-workers.yml .github/workflows/deploy.yml

# Configure secrets
gh secret set CLOUDFLARE_API_TOKEN

結果: main へのプッシュ時に自動デプロイされる新しい Worker

project-planning → オートメーションを生成

ユーザーが project-planning スキルを使用する場合：

# User: "Plan new React app with GitHub automation"

# project-planning generates IMPLEMENTATION_PHASES.md
# Then this skill sets up GitHub automation
cp templates/workflows/ci-react.yml .github/workflows/ci.yml
cp templates/issue-templates/*.yml .github/ISSUE_TEMPLATE/

結果: GitHub オートメーションが一式揃った計画済みのプロジェクト

open-source-contributions → コントリビューター向けの環境を設定

プロジェクトをオープンソースとして公開する準備をする場合：

# User: "Prepare repo for open source contributions"

# open-source-contributions skill handles CONTRIBUTING.md
# This skill adds issue templates and CODEOWNERS
cp templates/issue-templates/*.yml .github/ISSUE_TEMPLATE/
cp templates/misc/CODEOWNERS .github/

結果: コントリビューターに配慮したリポジトリ

---

依存関係

必須：

• Git 2.0+ - バージョン管理
• GitHub CLI (gh) 2.0+ - シークレット管理、PR の作成（任意ですが、推奨）

任意：

• yamllint 1.20+ - コミット前の YAML 検証
• act（ローカル GitHub Actions ランナー）- ワークフローのローカルテスト

gh CLI のインストール：

# macOS
brew install gh

# Ubuntu
sudo apt install gh

# Verify
gh --version

---

公式ドキュメント

• GitHub Actions: https://docs.github.com/en/actions
• ワークフローの構文: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
• CodeQL: https://codeql.github.com/docs/
• Dependabot: https://docs.github.com/en/code-security/dependabot
• Issue テンプレート: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests

Context7 ライブラリ ID: Context7 MCP で /websites/github または /github/ を検索してください

---

セットアップ完了チェックリスト

このチェックリストを使って、GitHub 自動化のセットアップを確認してください。

ワークフロー：

• .github/workflows/ ディレクトリを作成した
• 適切な CI ワークフローテンプレートをコピーした
• ワークフローファイル内のユーザー名を更新した
• シークレットを設定した（デプロイする場合）
• すべてのアクションを SHA で固定した（@latest は使用しない）
• ランナーのバージョンを明示した（ubuntu-24.04）
• ワークフローのトリガーがブランチ（main/master）と一致している

Issue テンプレート：

• .github/ISSUE_TEMPLATE/ ディレクトリを作成した
• bug_report.yml をコピーした
• feature_request.yml をコピーした
• 担当者を自分の GitHub ユーザー名に更新した
• YAML テンプレートで重要なフィールドに required: true を指定した

PR テンプレート：

• PULL_REQUEST_TEMPLATE.md を .github/ にコピーした
• プロジェクトのニーズに合わせてチェックリストをカスタマイズした

セキュリティ：

• security-codeql.yml をコピーした
• CodeQL マトリックスに適切な言語を追加した
• security-events: write 権限を設定した
• dependabot.yml をコピーした
• package-ecosystem（npm/pip など）を更新した
• dependabot.yml でレビュアーを設定した

テスト：

• 最初にフィーチャーブランチへプッシュした（main にはプッシュしない）
• CI が正常に実行されることを確認した
• Actions タブでエラーがないか確認した
• YAML 構文をローカルで検証した
• シークレットへのアクセスをテストした（該当する場合）

ドキュメント：

• README.md にバッジを追加した（任意）
• 必要なシークレットを README に記載した
• CONTRIBUTING.md を更新した（オープンソースの場合）

---

質問や問題がある場合：

1. 18 件すべてのエラーについては references/common-errors.md を確認してください
2. ワークフローの YAML が有効であることを確認してください：yamllint .github/workflows/*.yml
3. 詳細なエラーメッセージは GitHub Actions タブで確認してください
4. 公式ドキュメントを確認してください：https://docs.github.com/en/actions
5. シークレットが設定されていることを確認してください：gh secret list

---

最終更新日：2025-12-17 バージョン：2.0.0（段階的開示に合わせて最適化） ステータス：本番環境対応