github-project-automation

仓库: ovachiever/droid-tings
安装量: 44
排名: #16637

安装

npx skills add https://github.com/ovachiever/droid-tings --skill 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):

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: - jezweb # ← Change to your GitHub username

In dependabot.yml

reviewers: - "jezweb" # ← 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

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: Templates use explicit ubuntu-24.04

Issue #5: Multiple Keys with Same Name

Error: duplicate key found in mapping Source: YAML Parser Updates Why It Happens: Copy-paste errors, duplicate job/step names Prevention: Templates use unique, descriptive naming

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

Issue #7: Matrix Strategy Errors

Error: Matrix doesn't expand, tests skipped Source: Troubleshooting Guides Why It Happens: Invalid matrix config, wrong variable reference Prevention: Templates include working matrix examples

Issue #8: Context Syntax Errors

Error: Variables not interpolated, empty values Source: GitHub Actions Docs Why It Happens: Forgetting ${{ }} wrapper Prevention: Templates show all context patterns

Issue #9: Overly Complex Templates

Error: Contributors ignore template, incomplete issues Source: GitHub Best Practices Why It Happens: 20+ fields, asking irrelevant details Prevention: Skill templates are minimal (5-8 fields max)

Issue #10: Generic Prompts Without Context

Error: Vague bug reports, hard to reproduce Source: Template Best Practices Why It Happens: No guidance on what info is needed Prevention: Templates include specific placeholders

Issue #11: Multiple Template Confusion

Error: Users don't know which template to use Source: GitHub Docs Why It Happens: Using single ISSUE_TEMPLATE.md file Prevention: Proper ISSUE_TEMPLATE/ directory with config.yml

Issue #12: Missing Required Fields

Error: Incomplete issues, missing critical info Source: Community Feedback Why It Happens: Markdown templates don't validate Prevention: YAML templates with required: true

Issue #13: 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/**]

Issue #14: Branch Protection Blocking All PRs

Error: Legitimate PRs blocked, development stalled Source: Security Alerts Guide Why It Happens: Over-restrictive alert policies Prevention: Reference docs explain proper scoping

Issue #15: Compiled Language CodeQL Setup

Error: No code found to analyze Source: CodeQL Documentation Why It Happens: Missing build steps for Java/C++/C# Prevention: Templates include build examples

Issue #16: Development Dependencies Ignored

Error: Vulnerable devDependencies not scanned Source: Security Best Practices Why It Happens: Thinking devDependencies don't matter Prevention: Templates scan all dependencies

Issue #17: Dependabot Alert Limit

Error: Only 10 alerts auto-fixed, others queued Source: GitHub Docs (hard limit) Why It Happens: GitHub limits 10 open PRs per ecosystem Prevention: Templates document limit and workaround

Issue #18: Workflow Duplication

Error: Wasted CI minutes, maintenance overhead Source: DevSecOps Guides Why It Happens: Separate workflows for CI/CodeQL/dependency review Prevention: Templates offer integrated option

See: references/common-errors.md for detailed error documentation with examples

Configuration Files Reference dependabot.yml (Full Example) version: 2 updates: # npm dependencies (including devDependencies) - package-ecosystem: "npm" directory: "/" schedule: interval: "weekly" day: "monday" time: "09:00" timezone: "Australia/Sydney" open-pull-requests-limit: 10 # GitHub hard limit reviewers: - "jezweb" labels: - "dependencies" - "npm" commit-message: prefix: "chore" prefix-development: "chore" include: "scope"

# GitHub Actions - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly" open-pull-requests-limit: 5 labels: - "dependencies" - "github-actions"

Why these settings:

Weekly schedule reduces noise vs daily 10 PR limit matches GitHub maximum Includes devDependencies (Error #16 prevention) Reviewers auto-assigned for faster triage Conventional commit prefixes (chore: for deps) CodeQL Workflow (security-codeql.yml) name: CodeQL Security Scan

on: push: branches: [main, master] pull_request: branches: [main, master] schedule: - cron: '0 0 * * 0' # Weekly on Sundays

jobs: analyze: runs-on: ubuntu-24.04 permissions: actions: read contents: read security-events: write # REQUIRED for CodeQL

strategy:
  fail-fast: false
  matrix:
    language: ['javascript-typescript']  # Add your languages

steps:
  - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

  - name: Initialize CodeQL
    uses: github/codeql-action/init@ea9e4e37992a54ee68a9622e985e60c8e8f12d9f
    with:
      languages: ${{ matrix.language }}

  # For compiled languages, add build here

  - name: Perform CodeQL Analysis
    uses: github/codeql-action/analyze@ea9e4e37992a54ee68a9622e985e60c8e8f12d9f

Critical permissions:

security-events: write is REQUIRED for CodeQL uploads Without it, workflow fails silently Common Patterns Pattern 1: Multi-Framework Matrix Testing

Use for libraries that support multiple Node.js/Python versions:

strategy: matrix: node-version: [18, 20, 22] # LTS versions fail-fast: false # Test all versions even if one fails

steps: - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af with: node-version: ${{ matrix.node-version }} cache: 'npm' # Cache dependencies for speed

  • run: npm ci # Use ci (not install) for reproducible builds
  • run: npm test

When to use: Libraries, CLI tools, packages with broad version support

Pattern 2: Conditional Deployment

Deploy only on push to main (not PRs):

jobs: deploy: if: github.event_name == 'push' && github.ref == 'refs/heads/main' steps: - run: npx wrangler deploy env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

When to use: Production deployments, avoiding test deployments from PRs

Pattern 3: Artifact Upload/Download

Share build outputs between jobs:

jobs: build: steps: - run: npm run build - uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 with: name: build-output path: dist/ retention-days: 7

deploy: needs: build steps: - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 with: name: build-output path: dist/ - run: # Deploy from dist/

When to use: Separating build and deployment, sharing test results

Using Bundled Resources Scripts (scripts/)

Coming in Phase 3 - Automation scripts for common tasks:

setup-github-project.sh - Interactive setup wizard validate-workflows.sh - YAML validation before commit generate-codeowners.sh - Auto-generate from git log sync-templates.sh - Update existing projects

Example Usage:

./scripts/setup-github-project.sh react

Prompts for project details, generates .github/ structure

References (references/)

Load when needed for detailed error resolution:

references/common-errors.md - All 18 errors with solutions (complete) references/github-actions-reference.md - Complete Actions API (Phase 2) references/workflow-syntax.md - YAML syntax guide (Phase 2) references/dependabot-guide.md - Dependabot deep-dive (Phase 2) references/codeql-guide.md - CodeQL configuration (Phase 2) references/secrets-management.md - Secrets best practices (Phase 2) references/matrix-strategies.md - Matrix patterns (Phase 2)

When Claude should load these: When user encounters specific errors, needs deep configuration, or troubleshooting complex scenarios

Templates (templates/)

Complete collection - 45+ files organized by type:

Workflows (12 templates):

Phase 1 (complete): ci-basic, ci-node, ci-python, ci-react, ci-cloudflare-workers, security-codeql Phase 2: ci-matrix, cd-production, release, pr-checks, scheduled-maintenance, security-dependency-review

Issue Templates (4 templates):

Phase 1 (complete): bug_report.yml, feature_request.yml Phase 2: documentation.yml, config.yml

PR Templates (3 templates):

Phase 1 (complete): PULL_REQUEST_TEMPLATE.md Phase 2: feature.md, bugfix.md

Security (3 templates):

Phase 1 (complete): dependabot.yml Phase 2: SECURITY.md, codeql-config.yml

Misc (2 templates):

Phase 2: CODEOWNERS, FUNDING.yml 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

Advanced Topics Integrating with GitHub Projects v2

Status: Researched, not implemented (see /planning/github-projects-poc-findings.md)

Why separate skill: Complex GraphQL API, ID management, niche use case

When to consider: Team projects needing automated board management

Custom Workflow Composition

Combining workflows for efficiency:

Option A: Separate workflows (easier maintenance)

.github/workflows/ ci.yml # Test and build codeql.yml # Security scanning deploy.yml # Production deployment

Option B: Integrated workflow (fewer CI minutes)

.github/workflows/ main.yml # All-in-one: test, scan, deploy

Trade-off: Separate = clearer, Integrated = faster (Error #18 prevention)

Multi-Environment Deployments

Deploy to staging and production:

jobs: deploy-staging: if: github.ref == 'refs/heads/develop' steps: - run: npx wrangler deploy --env staging

deploy-production: if: github.ref == 'refs/heads/main' steps: - run: npx wrangler deploy --env production

Requires: Wrangler environments configured in wrangler.jsonc

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

Package Versions (Verified 2025-11-06)

GitHub Actions (SHA-pinned in templates):

actions/checkout: 11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 actions/setup-node: 39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 actions/setup-python: 0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0 actions/upload-artifact: b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3 actions/download-artifact: fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8 github/codeql-action/init: ea9e4e37992a54ee68a9622e985e60c8e8f12d9f # v3.27.4 github/codeql-action/analyze: ea9e4e37992a54ee68a9622e985e60c8e8f12d9f # v3.27.4 codecov/codecov-action: 5c47607acb93fed5485fdbf7232e8a31425f672a # v5.0.2

Verification Command:

Check latest action versions

gh api repos/actions/checkout/releases/latest gh api repos/github/codeql-action/releases/latest

Production Example

This skill is based on production testing across 3 projects:

Project 1: React App

Template Used: ci-react.yml Build Time: 2m 15s (CI), 45s (local) Errors: 0 (all 18 known issues prevented) Validation: ✅ Type checking, linting, testing, build, CodeQL

Project 2: Cloudflare Worker

Template Used: ci-cloudflare-workers.yml Deploy Time: 1m 30s (automated) Errors: 0 Validation: ✅ Deployed to production, Wrangler deployment successful

Project 3: Python CLI Tool

Template Used: ci-python.yml (matrix) Test Time: 3m 45s (3 Python versions in parallel) Errors: 0 Validation: ✅ Matrix testing on 3.10, 3.11, 3.12

Token Savings: ~70% (26,500 → 7,000 tokens avg)

Troubleshooting Problem: Workflow not triggering

Symptoms: Pushed code but CI doesn't run

Solutions:

Check workflow is in .github/workflows/ (not .github/workflow/) Verify YAML is valid: yamllint .github/workflows/*.yml Check trigger matches your branch: on: push: branches: [main] Ensure workflow file is committed and pushed Check Actions tab in GitHub for error messages Problem: CodeQL failing with "No code found"

Symptoms: CodeQL workflow completes but finds nothing

Solutions:

For compiled languages (Java, C++, C#), add build step: - name: Build project run: ./mvnw clean install

Verify language is correct in matrix: language: ['java-kotlin'] # Not just 'java'

Check CodeQL supports your language (see docs) Problem: Secrets not available in workflow

Symptoms: Secret not found or empty variable

Solutions:

Verify secret added to repository: gh secret list Check syntax uses double braces: ${{ secrets.NAME }} Secrets are case-sensitive (use exact name) For forks, secrets aren't available (security) Problem: Dependabot PRs keep failing

Symptoms: Automated PRs fail CI checks

Solutions:

Ensure CodeQL triggers on Dependabot PRs: on: push: branches: [dependabot/**]

Check branch protection doesn't block bot PRs Verify tests pass with updated dependencies locally Review Dependabot logs: Settings → Security → Dependabot Problem: Matrix builds all failing

Symptoms: All matrix jobs fail with same error

Solutions:

Check variable reference includes matrix.: node-version: ${{ matrix.node-version }} # NOT ${{ node-version }}

Verify matrix values are valid: matrix: node-version: [18, 20, 22] # Valid LTS versions

Use fail-fast: false to see all failures: strategy: fail-fast: false

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

Phase 1 Complete - Core templates and documentation ready Phase 2-4 Pending - Advanced workflows, scripts, additional guides

Last Updated: 2025-11-06 Version: 1.0.0 Status: Production Ready (Phase 1 Complete)

← 返回排行榜