secondsky/claude-skills / plugins/github-project-automation/skills/github-project-automation
github-project-automation
VerifiedGitHub 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.
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)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 468k | Updated | Claude CodeCodex | Verified | Install |
| 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: 468k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |