github-project-automation

# GitHub Project Automation **Status**: Production Ready ✅ **Last Updated**: 2025-12-17 **Version**: 2.0.0 (Optimized with progressive disclosure) **Dependencies**: None (git and gh CLI recommended) **Latest Versions**: actions/checkout@v4.2.2, actions/setup-node@v4.1.0, github/codeql-action@v3.27.4 --- ## Quick Start (15 Minutes) ### 1. Choose Your Framework Select the workflow template that matches your project: ```bash # 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 ``` **Why this matters:** - Pre-validated YAML prevents syntax errors - SHA-pinned actions for security - Explicit runner versions (ubuntu-24.04) - All 8 GitHub Actions errors prevented ### 2. Add Issue Templates ```bash # 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/ ``` **Why YAML over Markdown:** - Required field validation (Error #12 prevented) - Consistent data structure - Better user experience - No incomplete issues ### 3. Enable Security Scanning ```bash # 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 ``` **CRITICAL:** - CodeQL requires specific permissions (security-events: write) - Dependabot has 10 PR limit per ecosystem - Both must run on Dependabot PRs (Error #13 prevention) --- ## The 5-Step Complete Setup Process ### Step 1: Repository Structure Create the standard GitHub automation directory structure: ```bash # 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/) ``` **Key Points:** - workflows/ is plural - ISSUE_TEMPLATE/ is singular (legacy naming) - dependabot.yml goes in .github/, NOT workflows/ ### Step 2: Select Workflow Templates Choose workflows based on your project needs: **Continuous Integration (pick ONE):** 1. `ci-basic.yml` - Generic test/lint/build (all frameworks) 2. `ci-node.yml` - Node.js with matrix testing (18, 20, 22) 3. `ci-python.yml` - Python with matrix testing (3.10, 3.11, 3.12) 4. `ci-react.yml` - React/TypeScript with type checking **Deployment (optional):** 5. `ci-cloudflare-workers.yml` - Deploy to Cloudflare Workers **Security (recommended):** 6. `security-codeql.yml` - Code scanning 7. `dependabot.yml` - Dependency updates **Copy selected templates:** ```bash # 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 ``` ### Step 3: Configure Secrets (if deploying) For deployment workflows (Cloudflare, AWS, etc.), add secrets: ```bash # Using gh CLI gh secret set CLOUDFLARE_API_TOKEN # Paste your token when prompted # Verify gh secret list ``` **Critical Syntax:** ```yaml # ✅ CORRECT env: API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} # ❌ WRONG - Missing double braces env: API_TOKEN: $secrets.CLOUDFLARE_API_TOKEN ``` Prevents Error #6 (secrets syntax). ### Step 4: Add Issue/PR Templates **Issue templates (YAML format):** ```bash cp templates/issue-templates/bug_report.yml .github/ISSUE_TEMPLATE/ cp templates/issue-templates/feature_request.yml .github/ISSUE_TEMPLATE/ ``` **PR template (Markdown format):** ```bash cp templates/pr-templates/PULL_REQUEST_TEMPLATE.md .github/ ``` **Why separate formats:** - Issue templates: YAML for validation - PR template: Markdown (GitHub limitation) ### Step 5: Customize for Your Project **Required customizations:** 1. **Update usernames/emails:** ```yaml # In issue templates assignees: - secondsky # ← Change to your GitHub username # In dependabot.yml reviewers: - "secondsky" # ← Change to your username ``` 2. **Adjust languages (CodeQL):** ```yaml # In security-codeql.yml matrix: language: ['javascript-typescript'] # ← Add your languages # Options: c-cpp, csharp, go, java-kotlin, python, ruby, swift ``` 3. **Update package manager (Dependabot):** ```yaml # In dependabot.yml - package-ecosystem: "npm" # ← Change if using yarn/pnpm/pip/etc ``` 4. **Set deployment URL (Cloudflare):** ```yaml # In ci-cloudflare-workers.yml echo "Worker URL: https://your-worker.your-subdomain.workers.dev" # ← Update with your actual Worker URL ``` --- ## Critical Rules ### Always Do ✅ **Pin actions to SHA, not @latest** ```yaml # ✅ CORRECT - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 # ❌ WRONG - uses: actions/checkout@latest ``` ✅ **Use explicit runner versions** ```yaml # ✅ CORRECT runs-on: ubuntu-24.04 # Locked to specific LTS # ❌ RISKY runs-on: ubuntu-latest # Changes over time ``` ✅ **Include secrets in context syntax** ```yaml # ✅ CORRECT ${{ secrets.API_TOKEN }} # ❌ WRONG $secrets.API_TOKEN ``` ✅ **Validate YAML before committing** ```bash # Use yamllint or GitHub's workflow validator yamllint .github/workflows/*.yml ``` ✅ **Test workflows on feature branch first** ```bash git checkout -b test/github-actions # Push and verify CI runs before merging to main ``` ### Never Do ❌ **Don't use @latest for action versions** - Breaks without warning when actions update - Security risk (unvetted versions auto-adopted) ❌ **Don't hardcode secrets in workflows** ```yaml # ❌ NEVER DO THIS env: API_TOKEN: "sk_live_abc123..." # Secret exposed in repo! ``` ❌ **Don't skip build steps for compiled languages (CodeQL)** ```yaml # ❌ 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 ``` ❌ **Don't ignore devDependencies in Dependabot** - DevDependencies run during build, can execute malicious code - Include both prod and dev dependencies ❌ **Don't use single ISSUE_TEMPLATE.md file** ``` # ❌ OLD WAY .github/ISSUE_TEMPLATE.md # ✅ NEW WAY .github/ISSUE_TEMPLATE/ bug_report.yml feature_request.yml ``` --- ## Known Issues Prevention (Top 5) This skill prevents **18** documented issues. Here are the top 5 most critical: ### Issue #1: YAML Indentation Errors ⚠️ MOST COMMON **Error**: `workflow file is invalid. mapping values are not allowed in this context` **Source**: Stack Overflow (most common GitHub Actions error) **Why It Happens**: Spaces vs tabs, missing spaces after colons, inconsistent indentation **Prevention**: Use skill templates with validated 2-space indentation **Impact**: Workflow fails to parse, CI doesn't run ### Issue #2: Action Version Pinning Issues 🔒 SECURITY **Error**: Workflow breaks unexpectedly after action updates **Source**: GitHub Security Best Practices 2025 **Why It Happens**: Using `@latest` or `@v4` instead of specific SHA **Prevention**: All templates pin to SHA with version comment **Impact**: Unexpected breaking changes, security vulnerabilities ### Issue #3: Secrets Not Available 🔑 **Error**: `Secret not found` or empty variable **Source**: GitHub Actions Debugging Guides **Why It Happens**: Wrong syntax (`$secrets.NAME` instead of `${{ secrets.NAME }}`) **Prevention**: Templates demonstrate correct context syntax **Impact**: Deployment failures, broken CI/CD pipelines ### Issue #4: CodeQL Not Running on Dependabot PRs 🛡️ **Error**: Security scans skipped on dependency updates **Source**: GitHub Community Discussion #121836 **Why It Happens**: Default trigger limitations **Prevention**: Templates include `push: branches: [dependabot/**]` **Impact**: Vulnerable dependencies merged without scanning ### Issue #5: Missing Required Fields in Issue Templates 📋 **Error**: Incomplete issues, missing critical info **Source**: Community Feedback **Why It Happens**: Markdown templates don't validate **Prevention**: YAML templates with `required: true` validation **Impact**: Can't reproduce bugs, wasted triage time **For complete error documentation with all 18 issues**: Load `references/common-errors.md` when debugging GitHub Actions issues or configuring workflows. --- ## When to Load References Load reference files when working on specific aspects of GitHub automation: ### Common Errors (`references/common-errors.md`) Load when: - Encountering workflow syntax errors - Debugging failed GitHub Actions runs - Setting up CodeQL or Dependabot for first time - Resolving "Secret not found" errors - Understanding why matrix builds fail - Need detailed solutions for any of the 18 documented errors ### Workflow Patterns (`references/workflow-patterns.md`) Load when: - Implementing multi-version testing (Node.js 18/20/22) - Setting up conditional deployments (main vs PR) - Sharing build artifacts between jobs - Integrating GitHub automation with other skills (cloudflare-worker-base, project-planning) - Optimizing workflow performance - Need examples of matrix strategies, artifact upload/download ### Configuration Examples (`references/configuration-examples.md`) Load when: - Creating dependabot.yml from scratch - Configuring CodeQL for specific languages - Setting up GitHub Actions secrets correctly - Need complete working configuration files - Understanding branch protection rules - Creating issue/PR templates with proper validation ### Troubleshooting Guide (`references/troubleshooting-guide.md`) Load when: - Workflows not triggering despite pushing code - CodeQL reports "No code found to analyze" - Matrix builds all failing with same error - Dependabot PRs consistently failing CI - Permissions errors ("Resource not accessible by integration") - Need step-by-step debugging procedures ### Advanced Configurations (`references/advanced-configurations.md`) Load when: - Setting up multi-environment deployments (staging/production) - Creating reusable workflows or composite actions - Optimizing CI/CD pipeline performance - Implementing advanced matrix strategies - Using OIDC for cloud authentication (no long-lived secrets) - Need workflow optimization techniques --- ## Integration with Existing Skills ### cloudflare-worker-base → Add CI/CD When user creates new Worker project: ```bash # 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 ``` **Result**: New Worker with automated deployment on push to main ### project-planning → Generate Automation When user uses project-planning skill: ```bash # 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/ ``` **Result**: Planned project with complete GitHub automation ### open-source-contributions → Setup Contributor Experience When preparing project for open source: ```bash # 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/ ``` **Result**: Contributor-friendly repository --- ## Dependencies **Required**: - **Git** 2.0+ - Version control - **GitHub CLI (gh)** 2.0+ - Secret management, PR creation (optional but recommended) **Optional**: - **yamllint** 1.20+ - YAML validation before commit - **act** (local GitHub Actions runner) - Test workflows locally **Install gh CLI**: ```bash # macOS brew install gh # Ubuntu sudo apt install gh # Verify gh --version ``` --- ## Official Documentation - **GitHub Actions**: https://docs.github.com/en/actions - **Workflow Syntax**: 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 Templates**: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests **Context7 Library ID**: Search for `/websites/github` or `/github/` in Context7 MCP --- ## Complete Setup Checklist Use this checklist to verify your GitHub automation setup: **Workflows:**