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/troubleshooting-guide.md

View on GitHub
# GitHub Actions Troubleshooting Guide

Complete troubleshooting guide for GitHub Actions, CodeQL, and Dependabot issues.

**Last Updated**: 2025-12-17

---

## Table of Contents

1. [Workflow Not Triggering](#workflow-not-triggering)
2. [CodeQL Failing](#codeql-failing)
3. [Secrets Not Available](#secrets-not-available)
4. [Dependabot PRs Failing](#dependabot-prs-failing)
5. [Matrix Builds Failing](#matrix-builds-failing)
6. [YAML Syntax Errors](#yaml-syntax-errors)
7. [Permissions Issues](#permissions-issues)
8. [Advanced Debugging](#advanced-debugging)

---

## Workflow Not Triggering

### Symptoms
- Pushed code but CI doesn't run
- No workflow run in Actions tab
- Expected workflow missing from checks

### Solutions

#### 1. Check workflow directory
```bash
# ✅ CORRECT
.github/workflows/ci.yml

# ❌ WRONG
.github/workflow/ci.yml  # Missing 's'
.github/ci.yml            # Wrong location
workflows/ci.yml          # Missing .github/
```

#### 2. Verify YAML is valid
```bash
# Install yamllint
brew install yamllint  # macOS
sudo apt install yamllint  # Linux

# Validate all workflows
yamllint .github/workflows/*.yml
```

#### 3. Check trigger configuration
```yaml
# Workflow triggers on push to main
on:
  push:
    branches: [main]

# ❌ PROBLEM: You pushed to 'master' but workflow expects 'main'
# ✅ SOLUTION: Update branches list or rename branch
on:
  push:
    branches: [main, master]  # Support both
```

#### 4. Ensure workflow is committed
```bash
# Check if workflow file is tracked
git ls-files .github/workflows/

# If not listed, add it
git add .github/workflows/ci.yml
git commit -m "Add CI workflow"
git push
```

#### 5. Check Actions tab for errors
- Go to GitHub repo → Actions tab
- Look for workflow runs (even failed ones)
- Click on workflow run to see error messages
- Check "Set up job" step for initialization errors

### Common Causes
- Typo in directory name (`workflow` vs `workflows`)
- YAML syntax error (prevents workflow from parsing)
- Branch name mismatch (pushing to wrong branch)
- Workflow file not committed to repository
- Actions disabled in repository settings

---

## CodeQL Failing

### Problem 1: "No code found to analyze"

#### Symptoms
- CodeQL workflow completes but finds nothing
- Analysis step shows "0 files analyzed"
- No results in Security → Code scanning

#### Solutions for Compiled Languages

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

- 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-kotlin'

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

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

#### Solutions for JavaScript/TypeScript

```yaml
# For Node.js projects, CodeQL needs node_modules
- uses: github/codeql-action/init@v3
  with:
    languages: 'javascript-typescript'

# Install dependencies BEFORE autobuild
- run: npm ci

- uses: github/codeql-action/autobuild@v3
- uses: github/codeql-action/analyze@v3
```

### Problem 2: Language not detected

#### Symptoms
- Error: "Language 'X' not found in repository"
- CodeQL skips analysis

#### Solutions

```yaml
# ❌ WRONG - Incorrect language name
matrix:
  language: ['java']  # Should be 'java-kotlin'

# ✅ CORRECT - Use official language identifiers
matrix:
  language: ['java-kotlin']  # For Java/Kotlin
  # Options: c-cpp, csharp, go, java-kotlin,
  #          javascript-typescript, python, ruby, swift
```

### Problem 3: Permission denied

#### Symptoms
- Error: "Resource not accessible by integration"
- CodeQL upload fails

#### Solutions

```yaml
# ❌ MISSING - No permissions specified
jobs:
  analyze:
    runs-on: ubuntu-24.04
    steps:
      # CodeQL steps...

# ✅ CORRECT - Add required permissions
jobs:
  analyze:
    runs-on: ubuntu-24.04
    permissions:
      security-events: write  # REQUIRED for CodeQL
      contents: read
      actions: read
    steps:
      # CodeQL steps...
```

---

## Secrets Not Available

### Symptoms
- Error: `Secret XXX not found`
- Empty variable in workflow
- Workflow logs show blank values

### Solutions

#### 1. Verify secret exists
```bash
# List all secrets
gh secret list

# If secret missing, add it
gh secret set CLOUDFLARE_API_TOKEN
# Paste token when prompted
```

#### 2. Check syntax uses double braces
```yaml
# ❌ WRONG - Missing double braces
env:
  API_TOKEN: $secrets.CLOUDFLARE_API_TOKEN

# ❌ WRONG - Shell syntax (not GitHub Actions)
env:
  API_TOKEN: ${secrets.CLOUDFLARE_API_TOKEN}

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

#### 3. Verify case-sensitive name
```bash
# Secrets are case-sensitive!
# If you set: CLOUDFLARE_API_TOKEN
# Must use exact name in workflow

# ❌ WRONG
${{ secrets.cloudflare_api_token }}  # Lowercase

# ✅ CORRECT
${{ secrets.CLOUDFLARE_API_TOKEN }}  # Exact match
```

#### 4. Understand fork limitations
**Important**: Secrets are NOT available to forks for security reasons.

```yaml
# Solution: Use environments with protection rules
jobs:
  deploy:
    # Only run on main repo, not forks
    if: github.repository == 'owner/repo'
    environment: production  # Requires manual approval
    steps:
      - run: deploy-script
        env:
          SECRET: ${{ secrets.DEPLOY_SECRET }}
```

---

## Dependabot PRs Failing

### Problem: CodeQL/CI doesn't run on Dependabot PRs

#### Symptoms
- Dependabot PRs created but checks don't run
- Security scans skipped on dependency updates
- Branch protection blocks Dependabot PRs

#### Solutions

```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/**]
```

### Problem: Tests fail with updated dependencies

#### Solutions

```bash
# 1. Check Dependabot logs
# GitHub → Settings → Security → Dependabot alerts
# Click on specific PR to see detailed logs

# 2. Reproduce locally
git fetch origin
git checkout dependabot/npm_and_yarn/axios-1.6.0
npm install  # Install updated dependencies
npm test     # Run tests locally

# 3. Fix tests or update package
# If tests fail due to breaking changes:
# - Update code to handle breaking changes
# - Or ignore major version updates in dependabot.yml
```

### Problem: Branch protection blocks all Dependabot PRs

#### Solutions

```yaml
# dependabot.yml - Configure labels for easier management
labels:
  - "dependencies"
  - "automerge"  # Use with branch protection bypass

# Branch protection rules:
# ☑ Allow specified actors to bypass required pull requests
#   - dependabot[bot]  # For auto-merge of non-major updates
```

---

## Matrix Builds Failing

### Problem: All matrix jobs fail with same error

#### Symptoms
- All Node versions fail (18, 20, 22)
- Error message identical across jobs
- Matrix expansion seems correct

#### Solutions

#### 1. Check variable reference includes `matrix.`
```yaml
# ❌ WRONG - Missing matrix prefix
- uses: actions/setup-node@v4
  with:
    node-version: ${{ node-version }}  # ERROR: undefined

# ✅ CORRECT - Include matrix. prefix
- uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node-version }}  # SUCCESS
```

#### 2. Verify matrix values are valid
```yaml
# ❌ WRONG - Invalid Node versions
matrix:
  node-version: [17, 19, 21]  # Non-LTS versions

# ✅ CORRECT - Valid LTS versions
matrix:
  node-version: [18, 20, 22]  # LTS releases
```

#### 3. Use `fail-fast: false` to see all failures
```yaml
strategy:
  matrix:
    node-version: [18, 20, 22]
  fail-fast: false  # Don't stop on first failure

# Now all 3 jobs run even if one fails
# Easier to debug version-specific issues
```

### Problem: Matrix doesn't expand at all

#### Solutions

```yaml
# ❌ WRONG - Missing matrix values
strategy:
  matrix:
    node-version:  # ERROR: No array provided

# ❌ WRONG - Empty array
strategy:
  matrix:
    node-version: []  # ERROR: No values

# ✅ CORRECT - Array with values
strategy:
  matrix:
    node-version: [18, 20, 22]
```

---

## YAML Syntax Errors

### Common YAML Mistakes

```yaml
# ❌ WRONG - Tab character (use spaces!)
jobs:
	test:  # Tab character causes parse error
	  runs-on: ubuntu-24.04

# ✅ CORRECT - 2-space indentation
jobs:
  test:
    runs-on: ubuntu-24.04

# ❌ WRONG - Inconsistent indentation
jobs:
  test:
      runs-on: ubuntu-24.04  # 6 spaces
    steps:                    # 4 spaces
      - run: npm test         # 6 spaces

# ✅ CORRECT - Consistent 2-space indentation
jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - run: npm test

# ❌ WRONG - Missing space after colon
jobs:
  test:
    runs-on:ubuntu-24.04  # Missing space

# ✅ CORRECT - Space after colon
jobs:
  test:
    runs-on: ubuntu-24.04
```

### Validation Tools

```bash
# Install yamllint
brew install yamllint  # macOS
sudo apt install yamllint  # Linux

# Create .yamllint config
cat > .yamllint << 'EOF'
extends: default
rules:
  line-length:
    max: 120
  indentation:
    spaces: 2
EOF

# Validate workflows
yamllint .github/workflows/
```

---

## Permissions Issues

### Problem: "Resource not accessible by integration"

#### Cause
Missing or incorrect permissions in workflow.

#### Solutions

```yaml
# Default permissions (read-only)
permissions:
  contents: read

# Minimal required permissions
jobs:
  deploy:
    permissions:
      contents: read  # Checkout code
      deployments: write  # Create deployment
      id-token: write  # OIDC for cloud auth

  codeql:
    permissions:
      security-events: write  # Upload CodeQL results
      contents: read
      actions: read
```

### Problem: "403 Forbidden" when pushing to repo

#### Solutions

```yaml
# Option 1: Use GITHUB_TOKEN (default)
- run: git push
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Option 2: Use Personal Access Token (for protected branches)
- run: git push
  env:
    GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }}
```

---

## Advanced Debugging

### Enable Debug Logging

```bash
# Set repository secrets for debug output
gh secret set ACTIONS_STEP_DEBUG -b "true"
gh secret set ACTIONS_RUNNER_DEBUG -b "true"
```

### Add Debug Steps

```yaml
- name: Debug - Print Environment
  run: |
    echo "Event: ${{ github.event_name }}"
    echo "Ref: ${{ github.ref }}"
    echo "Actor: ${{ github.actor }}"
    echo "Repository: ${{ github.repository }}"
    env | sort

- name: Debug - Check Files
  run: |
    pwd
    ls -la
    git status
    git log --oneline -5
```

### Check Runner Environment

```yaml
- name: Debug - System Info
  run: |
    uname -a
    node --version
    npm --version
    git --version
    echo "PATH=$PATH"
```

---

**Last Updated**: 2025-12-17
**Version**: 1.0.0
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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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