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

ci-basic.yml - Generic test/lint/build (all frameworks)
ci-node.yml - Node.js with matrix testing (18, 20, 22)
ci-python.yml - Python with matrix testing (3.10, 3.11, 3.12)
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:

Update usernames/emails:

# In issue templates
assignees:
  - secondsky  # ← Change to your GitHub username

# In dependabot.yml
reviewers:
  - "secondsky"  # ← Change to your username

Adjust languages (CodeQL):

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

Update package manager (Dependabot):

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

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

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:

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

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

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

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

Created .github/workflows/ directory
Copied appropriate CI workflow template
Updated usernames in workflow files
Configured secrets (if deploying)
SHA-pinned all actions (not @latest)
Explicit runner version (ubuntu-24.04)
Workflow triggers match branches (main/master)

Issue Templates:

Created .github/ISSUE_TEMPLATE/ directory
Copied bug_report.yml
Copied feature_request.yml
Updated assignees to your GitHub username
YAML templates use required: true for critical fields

PR Template:

Copied PULL_REQUEST_TEMPLATE.md to .github/
Customized checklist for your project needs

Security:

Copied security-codeql.yml
Added correct languages to CodeQL matrix
Set security-events: write permission
Copied dependabot.yml
Updated package-ecosystem (npm/pip/etc.)
Set reviewers in dependabot.yml

Testing:

Pushed to feature branch first (not main)
Verified CI runs successfully
Checked Actions tab for any errors
Validated YAML syntax locally
Tested secret access (if applicable)

Documentation:

Added badge to README.md (optional)
Documented required secrets in README
Updated CONTRIBUTING.md (if open source)

Questions? Issues?

Check references/common-errors.md for all 18 errors
Verify workflow YAML is valid: yamllint .github/workflows/*.yml
Check GitHub Actions tab for detailed error messages
Review official docs: https://docs.github.com/en/actions
Ensure secrets are configured: gh secret list

Last Updated: 2025-12-17 Version: 2.0.0 (Optimized with progressive disclosure) Status: Production Ready

GitHub Project Automation

GitHub Project Automation

Quick Start (15 Minutes)

1. Choose Your Framework

2. Add Issue Templates

3. Enable Security Scanning

The 5-Step Complete Setup Process

Step 1: Repository Structure

Step 2: Select Workflow Templates

Step 3: Configure Secrets (if deploying)

Step 4: Add Issue/PR Templates

Step 5: Customize for Your Project

Critical Rules

Always Do

Never Do

Known Issues Prevention (Top 5)

Issue #1: YAML Indentation Errors ⚠️ MOST COMMON

Issue #2: Action Version Pinning Issues 🔒 SECURITY

Issue #3: Secrets Not Available 🔑

Issue #4: CodeQL Not Running on Dependabot PRs 🛡️

Issue #5: Missing Required Fields in Issue Templates 📋

When to Load References

Common Errors (references/common-errors.md)

Workflow Patterns (references/workflow-patterns.md)

Configuration Examples (references/configuration-examples.md)

Troubleshooting Guide (references/troubleshooting-guide.md)

Advanced Configurations (references/advanced-configurations.md)

Integration with Existing Skills

cloudflare-worker-base → Add CI/CD

project-planning → Generate Automation

open-source-contributions → Setup Contributor Experience

Dependencies

Official Documentation

Complete Setup Checklist

Similar Skills

Common Errors (`references/common-errors.md`)

Workflow Patterns (`references/workflow-patterns.md`)

Configuration Examples (`references/configuration-examples.md`)

Troubleshooting Guide (`references/troubleshooting-guide.md`)

Advanced Configurations (`references/advanced-configurations.md`)