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:

# 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

# 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

# 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:

# 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:

# 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:

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

# Verify
gh secret list

Critical Syntax:

# ✅ 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):

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

PR template (Markdown format):

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:

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

2. Adjust languages (CodeQL):

   # 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):

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

4. Set deployment URL (Cloudflare):

   # 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

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

# ❌ WRONG
- uses: actions/checkout@latest

✅ Use explicit runner versions

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

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

✅ Include secrets in context syntax

# ✅ CORRECT
${{ secrets.API_TOKEN }}

# ❌ WRONG
$secrets.API_TOKEN

✅ Validate YAML before committing

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

✅ Test workflows on feature branch first

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

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

❌ Don't skip build steps for compiled languages (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

❌ 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