Skip to content

secondsky/claude-skills / plugins/github-project-automation/skills/github-project-automation

github-project-automation

Verified

GitHub repository automation (CI/CD, issue templates, Dependabot, CodeQL). Use for project setup, Actions workflows, security scanning, or encountering YAML syntax, workflow configuration, template structure errors.

FileKindSize
SKILL.mdskill md15.6 KB
assets/example-template.txtmarkdown416 B
references/advanced-configurations.mdmarkdown9.4 KB
references/common-errors.mdmarkdown15.2 KB
references/configuration-examples.mdmarkdown11.6 KB
references/troubleshooting-guide.mdmarkdown10.8 KB
references/workflow-patterns.mdmarkdown10.9 KB
scripts/generate-codeowners.shexecutablescript4.1 KB
scripts/setup-github-project.shexecutablescript6.0 KB
scripts/sync-templates.shexecutablescript4.7 KB
scripts/validate-workflows.shexecutablescript4.9 KB
templates/issue-templates/bug_report.ymlconfig3.2 KB
templates/issue-templates/config.ymlconfig568 B
templates/issue-templates/documentation.ymlconfig2.5 KB
templates/issue-templates/feature_request.ymlconfig2.8 KB
templates/misc/CODEOWNERSother1.7 KB
templates/misc/FUNDING.ymlconfig803 B
templates/pr-templates/PULL_REQUEST_TEMPLATE.mdmarkdown1.9 KB
templates/pr-templates/bugfix.mdmarkdown1.4 KB
templates/pr-templates/feature.mdmarkdown1.7 KB
templates/security/SECURITY.mdmarkdown3.4 KB
templates/security/codeql-config.ymlconfig1.4 KB
templates/security/dependabot.ymlconfig1.7 KB
templates/workflows/cd-production.ymlconfig2.8 KB
templates/workflows/ci-basic.ymlconfig1.4 KB
templates/workflows/ci-cloudflare-workers.ymlconfig2.3 KB
templates/workflows/ci-matrix.ymlconfig1.8 KB
templates/workflows/ci-node.ymlconfig1.6 KB
templates/workflows/ci-python.ymlconfig1.8 KB
templates/workflows/ci-react.ymlconfig2.8 KB
templates/workflows/pr-checks.ymlconfig6.0 KB
templates/workflows/release.ymlconfig6.1 KB
templates/workflows/scheduled-maintenance.ymlconfig4.1 KB
templates/workflows/security-codeql.ymlconfig2.1 KB
templates/workflows/security-dependency-review.ymlconfig1.5 KB

references/common-errors.md

View on GitHub
# Common Errors in GitHub Automation - Complete Reference

This document catalogs **18 documented errors** that this skill prevents, with sources and solutions.

**Last Updated**: 2025-11-06
**Sources**: Stack Overflow, GitHub Issues, Community Discussions, Official Docs

---

## Table of Contents

1. [GitHub Actions Syntax Errors (8 issues)](#github-actions-syntax-errors)
2. [Issue/PR Templates (4 issues)](#issuepr-templates)
3. [Dependabot & Security (6 issues)](#dependabot--security)

---

## GitHub Actions Syntax Errors

### Error #1: YAML Indentation Errors

**Frequency**: Most Common
**Source**: Stack Overflow, GitHub Issues
**Impact**: Workflow fails to parse, CI doesn't run

**Cause**:
- Spaces vs tabs confusion
- Incorrect indentation levels
- Missing spaces after colons

**Examples**:
```yaml
# ❌ WRONG - Missing spaces
jobs:
test:
  runs-on:ubuntu-latest

# ❌ WRONG - Inconsistent indentation
jobs:
  test:
      runs-on: ubuntu-latest  # 6 spaces instead of 4
    steps:                    # 4 spaces

# ✅ CORRECT - Consistent 2-space indentation
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
```

**Solution**: Use skill templates with correct formatting

---

### Error #2: Missing `run` or `uses` Field

**Frequency**: Common
**Source**: GitHub Actions Error Logs
**Impact**: "Error: Step must have a `run` or `uses` key"

**Cause**:
- Empty step definition
- Forgetting to add the actual command

**Examples**:
```yaml
# ❌ WRONG - Empty step
steps:
  - name: Run tests

# ❌ WRONG - Only name provided
steps:
  - name: Build project
    env:
      NODE_ENV: production

# ✅ CORRECT - Has `run` field
steps:
  - name: Run tests
    run: npm test

# ✅ CORRECT - Has `uses` field
steps:
  - name: Checkout
    uses: actions/checkout@v4
```

**Solution**: Templates include complete step definitions

---

### Error #3: Action Version Pinning Issues

**Frequency**: Common
**Source**: GitHub Best Practices 2025
**Impact**: Unexpected breaking changes, security vulnerabilities

**Cause**:
- Using `@latest` or `@v4` instead of specific SHA or semver
- Actions update and break your workflow

**Examples**:
```yaml
# ❌ WRONG - @latest is unpredictable
- uses: actions/checkout@latest

# ❌ WRONG - Major version only
- uses: actions/checkout@v4

# ✅ GOOD - Semantic version
- uses: actions/checkout@v4.2.2

# ✅ BEST - Pinned to SHA (most secure)
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
```

**Solution**: Skill templates pin to specific SHA with version comment

---

### Error #4: Incorrect Runner Version

**Frequency**: Common
**Source**: CI/CD Troubleshooting Guides
**Impact**: Unexpected environment changes, compatibility issues

**Cause**:
- Using `ubuntu-latest` without understanding it changes
- Not aware that `ubuntu-latest` moved from 22.04 → 24.04 in 2024

**Examples**:
```yaml
# ❌ RISKY - Version changes over time
runs-on: ubuntu-latest  # Currently 24.04, was 22.04

# ✅ BETTER - Explicit version
runs-on: ubuntu-24.04   # Locked to specific LTS

# ✅ BEST - Document why you chose this version
runs-on: ubuntu-24.04  # Using 24.04 for Node.js 20 support
```

**Solution**: Templates use explicit `ubuntu-24.04`

---

### Error #5: Multiple Keys with Same Name

**Frequency**: Rare but Breaking
**Source**: YAML Parser Updates
**Impact**: YAML parse error, workflow invalid

**Cause**:
- Duplicate job names
- Duplicate step names
- Copy-paste errors

**Examples**:
```yaml
# ❌ WRONG - Duplicate job names
jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - run: npm test

  test:  # ERROR: Duplicate key
    runs-on: ubuntu-24.04
    steps:
      - run: npm run lint

# ✅ CORRECT - Unique job names
jobs:
  test-unit:
    runs-on: ubuntu-24.04
    steps:
      - run: npm test

  test-lint:
    runs-on: ubuntu-24.04
    steps:
      - run: npm run lint
```

**Solution**: Templates use unique, descriptive naming conventions

---

### Error #6: Secrets Not Available

**Frequency**: Common
**Source**: GitHub Actions Debugging
**Impact**: "Secret not found" error, deployment failures

**Cause**:
- Incorrect syntax: `$SECRETS.NAME` instead of `${{ secrets.NAME }}`
- Secret not added to repository settings
- Wrong secret name

**Examples**:
```yaml
# ❌ WRONG - Missing double braces
env:
  API_TOKEN: $secrets.API_TOKEN

# ❌ WRONG - Wrong syntax
env:
  API_TOKEN: ${secrets.API_TOKEN}

# ✅ CORRECT - Proper context syntax
env:
  API_TOKEN: ${{ secrets.API_TOKEN }}

# ✅ CORRECT - Inline usage
- run: echo "Token: ${{ secrets.API_TOKEN }}"
```

**Solution**: Templates show correct `${{ secrets.NAME }}` syntax

---

### Error #7: Matrix Strategy Errors

**Frequency**: Common
**Source**: Troubleshooting Guides
**Impact**: Matrix doesn't expand correctly, tests don't run

**Cause**:
- Invalid matrix configuration
- Missing `fail-fast` setting
- Incorrect variable reference

**Examples**:
```yaml
# ❌ WRONG - Missing matrix values
strategy:
  matrix:
    node-version:  # ERROR: No values

# ❌ WRONG - Incorrect variable reference
strategy:
  matrix:
    node-version: [18, 20]
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ node-version }}  # Missing matrix.

# ✅ CORRECT - Complete matrix
strategy:
  matrix:
    node-version: [18, 20, 22]
  fail-fast: false
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node-version }}
```

**Solution**: Templates include working matrix examples

---

### Error #8: Context Syntax Errors

**Frequency**: Common
**Source**: GitHub Actions Docs
**Impact**: Variables not interpolated, empty values

**Cause**:
- Forgetting `${{ }}` wrapper
- Wrong context name (`github.branch` instead of `github.ref`)

**Examples**:
```yaml
# ❌ WRONG - No context wrapper
- name: Print branch
  run: echo github.ref

# ❌ WRONG - Incorrect context
- name: Check branch
  if: github.branch == 'main'  # Should be github.ref

# ✅ CORRECT - Proper context syntax
- name: Print branch
  run: echo "${{ github.ref }}"

# ✅ CORRECT - Branch check
- name: Deploy
  if: github.ref == 'refs/heads/main'
```

**Solution**: Templates demonstrate correct context usage

---

## Issue/PR Templates

### Error #9: Overly Complex Templates

**Frequency**: Common
**Source**: GitHub Best Practices
**Impact**: Contributors ignore template, provide incomplete info

**Cause**:
- Too many fields (20+ questions)
- Asking for irrelevant details
- No clear prioritization

**Examples**:
```markdown
❌ TOO COMPLEX (users skip it):
- Environment
  - OS
  - OS Version
  - Architecture
  - Locale
  - Timezone
  - Shell
  - Terminal emulator
  - Node version
  - npm version
  - yarn version
  - Browser
  - Browser version
  - Screen resolution
  - ...20 more fields

✅ FOCUSED (users complete it):
- OS: [Windows/macOS/Linux]
- Browser: [Chrome/Firefox/Safari]
- Version: [e.g. 1.2.3]
```

**Solution**: Skill templates are minimal and focused (5-8 fields max)

---

### Error #10: Generic Prompts Without Context

**Frequency**: Common
**Source**: Template Best Practices
**Impact**: Vague bug reports, hard to reproduce

**Cause**:
- Prompts like "Steps to reproduce" without examples
- No guidance on what information is needed

**Examples**:
```yaml
# ❌ VAGUE
- type: textarea
  attributes:
    label: Steps to Reproduce
    description: How to reproduce the issue

# ✅ SPECIFIC
- type: textarea
  attributes:
    label: Steps to Reproduce
    description: Detailed steps to reproduce the behavior
    placeholder: |
      1. Go to '...'
      2. Click on '...'
      3. Scroll down to '...'
      4. See error
```

**Solution**: Templates include specific, actionable prompts

---

### Error #11: Multiple Template Confusion

**Frequency**: Common
**Source**: GitHub Docs
**Impact**: Users don't know which template to use

**Cause**:
- Using single `ISSUE_TEMPLATE.md` file
- Not using `ISSUE_TEMPLATE/` directory

**Examples**:
```
❌ OLD WAY (confusing):
.github/
  ISSUE_TEMPLATE.md  # Only one template available

✅ NEW WAY (clear choices):
.github/
  ISSUE_TEMPLATE/
    bug_report.yml      # Bug reports
    feature_request.yml # Feature requests
    documentation.yml   # Docs updates
    config.yml          # Template configuration
```

**Solution**: Skill uses proper `ISSUE_TEMPLATE/` directory structure

---

### Error #12: Missing Required Fields

**Frequency**: Common
**Source**: Community Feedback
**Impact**: Incomplete issues, missing critical info

**Cause**:
- Markdown templates don't validate
- No required field enforcement

**Examples**:
```markdown
❌ MARKDOWN TEMPLATE (no validation):
## Bug Description
<!-- User can leave this blank -->

## Steps to Reproduce
<!-- User can leave this blank -->

✅ YAML TEMPLATE (validation):
- type: textarea
  id: description
  attributes:
    label: Bug Description
  validations:
    required: true  # GitHub enforces this!
```

**Solution**: Skill uses YAML templates with required field validation

---

## Dependabot & Security

### Error #13: CodeQL Not Running on Dependabot PRs

**Frequency**: Common
**Source**: GitHub Community Discussion #121836
**Impact**: Security scans skipped on dependency updates

**Cause**:
- Default setup limitations
- Permissions issues on Dependabot PRs
- Branch protection rules

**Examples**:
```yaml
# ❌ DOESN'T RUN ON DEPENDABOT
on:
  pull_request:
    branches: [main]

# ✅ INCLUDES DEPENDABOT
on:
  pull_request:
    branches: [main]
  # Dependabot creates PRs from special branches
  push:
    branches: [dependabot/**]
```

**Solution**: Templates include proper trigger configuration

---

### Error #14: Branch Protection Blocking All PRs

**Frequency**: Common
**Source**: Security Alerts Guide
**Impact**: Legitimate PRs blocked, development stalled

**Cause**:
- Over-restrictive alert policies
- Requiring ALL security checks pass
- Not exempting minor alerts

**Examples**:
```
❌ TOO RESTRICTIVE:
Branch protection requires:
  ✓ All security alerts resolved (blocks devDependencies alerts)
  ✓ All CodeQL checks pass (blocks on info-level findings)

✅ BALANCED:
Branch protection requires:
  ✓ Critical/High security alerts resolved
  ✓ CodeQL error-level checks pass
  ⚠ Medium/Low alerts can be addressed later
```

**Solution**: Reference docs explain proper protection scoping

---

### Error #15: Compiled Language CodeQL Setup

**Frequency**: Common for Java/C++/C#
**Source**: CodeQL Documentation
**Impact**: CodeQL fails with "No code found"

**Cause**:
- Missing build steps
- CodeQL can't analyze without compiled artifacts

**Examples**:
```yaml
# ❌ WRONG - No build step for Java
- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: 'java'

- name: Perform CodeQL Analysis  # FAILS - no .class files
  uses: github/codeql-action/analyze@v3

# ✅ CORRECT - Include build
- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: 'java'

- name: Build project
  run: ./mvnw clean install  # Creates .class files

- name: Perform CodeQL Analysis  # SUCCESS
  uses: github/codeql-action/analyze@v3
```

**Solution**: Templates include build steps for compiled languages

---

### Error #16: Development Dependencies Ignored

**Frequency**: Common
**Source**: Security Best Practices
**Impact**: Vulnerable devDependencies not scanned

**Cause**:
- Thinking devDependencies don't matter
- Not enabling full dependency scanning

**Examples**:
```yaml
# ❌ WRONG - Ignores devDependencies
ignore:
  - dependency-name: "*"
    dependency-type: development

# ✅ CORRECT - Includes all dependencies
# No ignore rules, or specific exclusions only
ignore:
  - dependency-name: "webpack"
    update-types: ["version-update:semver-major"]
```

**Why This Matters**: DevDependencies run during build, can execute malicious code

**Solution**: Templates scan both prod and dev dependencies

---

### Error #17: Dependabot Alert Limit

**Frequency**: Common for large projects
**Source**: GitHub Docs
**Impact**: Only 10 alerts auto-fixed, others require manual review

**Cause**:
- GitHub limits Dependabot to 10 open PRs per ecosystem
- Large projects exceed this quickly

**Examples**:
```
❌ PROBLEM: 50 outdated npm packages
Dependabot creates:
  ✓ 10 PRs (auto-opened)
  ❌ 40 alerts (queued, not opened)

✅ SOLUTION: Increase open-pull-requests-limit
# dependabot.yml
- package-ecosystem: "npm"
  open-pull-requests-limit: 10  # Default
  # Still capped at 10 by GitHub!

WORKAROUND:
1. Merge PRs in batches
2. Use @dependabot rebase for stale PRs
3. Manually update remaining packages
```

**Solution**: Templates document this limitation, reference workaround

---

### Error #18: Workflow Duplication

**Frequency**: Common
**Source**: DevSecOps Guides
**Impact**: Maintenance overhead, confusion, wasted CI time

**Cause**:
- Separate workflows for CI, CodeQL, Dependabot review
- All run similar setup steps

**Examples**:
```
❌ DUPLICATED WORKFLOWS:
.github/workflows/
  ci.yml              # Checkout, setup, test
  codeql.yml          # Checkout, setup, scan
  dependency-review.yml  # Checkout, setup, review

Total: 3× checkout, 3× setup, 3× CI minutes

✅ INTEGRATED WORKFLOW:
.github/workflows/
  ci-security.yml     # Checkout, setup ONCE, then:
                      # - test
                      # - CodeQL scan
                      # - dependency review

Total: 1× checkout, 1× setup, optimized
```

**Solution**: Templates offer both separate and integrated options

---

## Summary Table

| # | Error | Frequency | Impact | Prevented By |
|---|-------|-----------|--------|--------------|
| 1 | YAML Indentation Errors | Very High | Parse failure | Pre-validated templates |
| 2 | Missing run/uses Field | High | Step failure | Complete step definitions |
| 3 | Action Version Pinning | High | Breaking changes | SHA-pinned actions |
| 4 | Incorrect Runner Version | High | Compatibility | Explicit ubuntu-24.04 |
| 5 | Duplicate YAML Keys | Low | Parse failure | Unique naming |
| 6 | Secrets Syntax Errors | High | Deployment failure | Correct context syntax |
| 7 | Matrix Strategy Errors | Medium | Test skipped | Working matrix examples |
| 8 | Context Syntax Errors | High | Empty variables | Context reference guide |
| 9 | Overly Complex Templates | High | Low completion | Minimal templates |
| 10 | Generic Prompts | High | Vague reports | Specific placeholders |
| 11 | Multiple Template Confusion | Medium | Wrong template | Proper directory structure |
| 12 | Missing Required Fields | High | Incomplete issues | YAML validation |
| 13 | CodeQL Not on Dependabot | Medium | Security gap | Proper triggers |
| 14 | Branch Protection Blocking | Medium | Dev stalled | Scoped rules guide |
| 15 | Compiled Language CodeQL | Medium | Scan failure | Build steps |
| 16 | DevDependencies Ignored | High | Vulnerable deps | Full scanning |
| 17 | Dependabot Alert Limit | Medium | Manual work | Document limit |
| 18 | Workflow Duplication | Medium | Wasted CI | Integrated templates |

**Total**: 18 documented errors with solutions

---

## How This Skill Prevents These Errors

1. **Pre-validated Templates**: All YAML is tested and correct
2. **SHA-pinned Actions**: Security best practices built-in
3. **Complete Examples**: No guessing about syntax
4. **Reference Guides**: All 18 errors documented with fixes
5. **Validation Scripts**: Check before committing

**Result**: 100% error prevention vs manual setup

---

**Last Verified**: 2025-11-06
**Next Review**: 2026-02-06 (Quarterly)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall