github-project-automation

GitHub Project Automation

Status: Production Ready ✅ Last Updated: 2025-11-06 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):

1. ci-cloudflare-workers.yml - Deploy to Cloudflare Workers

Security (recommended):

1. security-codeql.yml - Code scanning
2. 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:

```yaml # In issue templates assignees:

• jezweb # ← Change to your GitHub username

# In dependabot.yml reviewers:

• "jezweb" # ← Change to your username

```

1. 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 ``

1. Update package manager (Dependabot):

```yaml # In dependabot.yml

• package-ecosystem: "npm" # ← Change if using yarn/pnpm/pip/etc

```

1. 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

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

This skill prevents 18 documented issues:

Issue #1: YAML Indentation Errors

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

Issue #2: Missing run or uses Field

Error: Error: Step must have a run or uses key Source: GitHub Actions Error Logs Why It Happens: Empty step definition, forgetting to add command Prevention: Templates include complete step definitions

Issue #3: Action Version Pinning Issues

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

Issue #4: Incorrect Runner Version

Error: Unexpected environment changes, compatibility issues Source: CI/CD Troubleshooting Guides Why It Happens: ubuntu-latest changed from 22.04 → 24.04 in 2024 Prevention: Temp