github-project-automation

What this skill does

# GitHub Project Automation

**Status**: Production Ready ✅
**Last Updated**: 2025-11-06
**Dependencies**: None (git and gh CLI recommended)
**Latest Versions**: actions/[email protected], actions/[email protected], github/[email protected]

---

## 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:
     - jezweb  # ← Change to your GitHub username
   
   # In dependabot.yml
   reviewers:
     - "jezweb"  # ← 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

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**: Tem