Cursor rule

1---
2alwaysApply: true
3description: Expert guidance for testing and validating GitHub Actions workflows before deployment - catches cache errors, path issues, monorepo dependencies, and service container problems that local testing misses
4---
5 
6## Description
7 
8Interactive expert for testing and validating GitHub Actions workflows before deployment. Prevents common CI failures by catching cache configuration errors, path issues, monorepo dependency problems, and service container configuration mistakes.
9 
10## Capabilities
11 
12This skill provides:
13 
141. **Pre-Push Validation**: Complete workflow validation before pushing to GitHub
152. **Cache Configuration**: Ensure cache-dependency-path is correctly specified
163. **Monorepo Build Order**: Validate workspace dependency build sequences
174. **Service Container Setup**: Guide proper service container configuration
185. **Path Validation**: Verify all paths exist and are accessible
196. **Local Testing**: Run workflows locally with act (Docker-based simulation)
207. **Static Analysis**: Lint workflows with actionlint and yamllint
21 
22## When to Use This Skill
23 
24Invoke this skill when:
25- Creating or modifying GitHub Actions workflows
26- Debugging workflow failures in CI
27- Setting up new repositories with CI/CD
28- Migrating to monorepo architecture
29- Adding service containers to workflows
30- Experiencing cache-related failures
31- Getting "module not found" errors in CI but not locally
32 
33## Usage
34 
35### Quick Validation
36 
37"Validate my GitHub Actions workflows before I push"
38 
39I'll:
401. Run actionlint on all workflow files
412. Check for missing cache-dependency-path configurations
423. Validate all working-directory paths exist
434. Verify monorepo build order is correct
445. Check service container configurations
456. Provide a pre-push checklist
46 
47### Debugging Workflow Failures
48 
49"My GitHub Actions workflow is failing with [error message]"
50 
51I'll:
521. Analyze the error message
532. Identify the root cause
543. Explain why local testing didn't catch it
554. Provide the correct configuration
565. Show how to test the fix locally
57 
58### Setup New Repository
59 
60"Set up GitHub Actions testing for my new project"
61 
62I'll:
631. Install required tools (act, actionlint, yamllint)
642. Create validation scripts
653. Set up pre-push hooks
664. Configure recommended workflows
675. Provide testing procedures
68 
69## Critical Rules I Enforce
70 
71### 1. Cache Configuration
72 
73**ALWAYS specify cache-dependency-path explicitly:**
74 
75```yaml
76# ❌ WRONG
77- uses: actions/setup-node@v4
78  with:
79    cache: 'npm'
80 
81# ✅ CORRECT
82- uses: actions/setup-node@v4
83  with:
84    cache: 'npm'
85    cache-dependency-path: package-lock.json
86```
87 
88**Why**: GitHub Actions cache resolution fails silently in local testing but errors in CI with "Some specified paths were not resolved, unable to cache dependencies."
89 
90### 2. Monorepo Build Order
91 
92**ALWAYS build workspace dependencies before type checking:**
93 
94```yaml
95# ❌ WRONG
96- run: npm ci
97- run: npx tsc --noEmit
98 
99# ✅ CORRECT
100- run: npm ci
101- run: npm run build --workspace=@prpm/types
102- run: npm run build --workspace=@prpm/registry-client
103- run: npx tsc --noEmit
104```
105 
106**Why**: TypeScript needs compiled output from workspace dependencies. Local development has pre-built artifacts, but CI starts clean.
107 
108### 3. npm ci in Monorepos
109 
110**ALWAYS run npm ci from root, not workspace directories:**
111 
112```yaml
113# ❌ WRONG
114- working-directory: packages/infra
115  run: npm ci
116 
117# ✅ CORRECT
118- run: npm ci
119- working-directory: packages/infra
120  run: pulumi preview
121```
122 
123**Why**: npm workspaces are managed from root. Workspace directories don't have their own package-lock.json.
124 
125### 4. Service Containers
126 
127**Service containers can't override CMD via options:**
128 
129```yaml
130# ❌ WRONG
131services:
132  minio:
133    image: minio/minio:latest
134    options: server /data  # Ignored!
135 
136# ✅ CORRECT
137services:
138  minio:
139    image: minio/minio:latest
140
141steps:
142  - run: |
143      docker exec $(docker ps -q --filter ancestor=minio/minio:latest) \
144        sh -c "minio server /data &"
145```
146 
147**Why**: GitHub Actions service containers ignore custom commands. They must be started manually in steps.
148 
149## Validation Tools
150 
151### Required Tools
152 
153```bash
154# macOS
155brew install act actionlint yamllint
156 
157# Linux
158curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
159bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
160pip install yamllint
161```
162 
163### Validation Script
164 
165I'll create `.github/scripts/validate-workflows.sh`:
166 
167```bash
168#!/bin/bash
169set -e
170
171echo "🔍 Validating GitHub Actions workflows..."
172 
173# 1. Static analysis
174actionlint .github/workflows/*.yml
175yamllint .github/workflows/*.yml
176 
177# 2. Cache configuration check
178for file in .github/workflows/*.yml; do
179    if grep -q "cache: 'npm'" "$file"; then
180        if ! grep -A 2 "cache: 'npm'" "$file" | grep -q "cache-dependency-path"; then
181            echo "❌ $file: Missing explicit cache-dependency-path"
182            exit 1
183        fi
184    fi
185done
186 
187# 3. Path validation
188grep -r "working-directory:" .github/workflows/*.yml | while read -r line; do
189    dir=$(echo "$line" | sed 's/.*working-directory: //' | tr -d '"')
190    if [ ! -d "$dir" ]; then
191        echo "❌ Directory does not exist: $dir"
192        exit 1
193    fi
194done
195 
196# 4. Check for explicit cache paths
197grep -r "cache-dependency-path:" .github/workflows/*.yml | while read -r line; do
198    path=$(echo "$line" | sed 's/.*cache-dependency-path: //' | tr -d '"')
199    if [ ! -f "$path" ]; then
200        echo "❌ Cache dependency path does not exist: $path"
201        exit 1
202    fi
203done
204
205echo "✅ All workflow validations passed"
206```
207 
208### Pre-Push Checklist
209 
210Before pushing workflow changes:
211 
2121. **Lint**: `actionlint .github/workflows/*.yml`
2132. **Validate**: `.github/scripts/validate-workflows.sh`
2143. **Dry Run**: `act pull_request -W .github/workflows/[workflow].yml -n`
2154. **Check Cache Paths**: Verify all cache-dependency-path values exist
2165. **Check Build Order**: Ensure workspace dependencies built before type checks
2176. **Service Containers**: Confirm manual startup if custom commands needed
218 
219## Common Failure Patterns
220 
221### "Cannot find module '@prpm/types'"
222 
223**Root Cause**: Workspace dependency not built before type checking
224 
225**Why Local Works**: Previous builds exist in node_modules/
226 
227**Fix**:
228```yaml
229- name: Build @prpm/types
230  run: npm run build --workspace=@prpm/types
231- name: Type check
232  run: npx tsc --noEmit
233```
234 
235### "Cache resolution error"
236 
237**Root Cause**: Missing or incorrect cache-dependency-path
238 
239**Why act Doesn't Catch**: act skips caching entirely
240 
241**Fix**:
242```yaml
243- uses: actions/setup-node@v4
244  with:
245    cache: 'npm'
246    cache-dependency-path: package-lock.json  # Explicit!
247```
248 
249### "npm ci requires package-lock.json"
250 
251**Root Cause**: Running npm ci from workspace directory
252 
253**Why Local Works**: May have workspace-specific package-lock.json
254 
255**Fix**:
256```yaml
257# Run from root
258- run: npm ci
259# Then use working-directory for commands
260- working-directory: packages/infra
261  run: pulumi preview
262```
263 
264### "Service container not starting"
265 
266**Root Cause**: Custom command in options is ignored
267 
268**Why Local Works**: docker-compose uses different container runtime
269 
270**Fix**:
271```yaml
272steps:
273  - run: docker exec [container] sh -c "command &"
274```
275 
276## Why act Alone Isn't Enough
277 
278Local testing with `act` doesn't catch:
279 
2801. **Cache Validation**: act skips GitHub's cache system entirely
2812. **Service Commands**: Different container runtime, different behavior
2823. **Build Artifacts**: Local has pre-built workspace dependencies
2834. **Clean Environment**: CI starts completely fresh every time
2845. **GitHub-Specific Features**: Some actions only work on GitHub's runners
285 
286**Solution**: Use the complete validation suite (actionlint + custom validators + act dry run)
287 
288## Interactive Debugging
289 
290When you encounter a workflow failure:
291 
2921. **Share the error**: Paste the exact GitHub Actions error message
2932. **I'll analyze**: Identify the root cause and why local testing didn't catch it
2943. **I'll fix**: Provide corrected workflow configuration
2954. **I'll validate**: Show how to test the fix locally
2965. **I'll explain**: Clarify why the issue occurred and how to prevent it
297 
298## Example Interactions
299 
300**User**: "My workflow is failing with 'Some specified paths were not resolved, unable to cache dependencies'"
301 
302**Me**: This is a cache resolution error. You're using `cache: 'npm'` without specifying `cache-dependency-path`. GitHub Actions is trying to find package-lock.json but can't locate it.
303 
304Here's the fix:
305```yaml
306- uses: actions/setup-node@v4
307  with:
308    node-version: '20'
309    cache: 'npm'
310    cache-dependency-path: package-lock.json  # Add this
311```
312 
313This wasn't caught by `act` because it skips caching entirely. To prevent this in the future, run:
314```bash
315.github/scripts/validate-workflows.sh
316```
317 
318This script checks for missing cache-dependency-path configurations.
319 
320---
321 
322**User**: "TypeScript can't find '@prpm/types' in CI but works locally"
323 
324**Me**: This is a monorepo build order issue. Your local environment has previously built `@prpm/types`, but CI starts clean.
325 
326Add this before your type check:
327```yaml
328- name: Build @prpm/types
329  run: npm run build --workspace=@prpm/types
330```
331 
332Why local worked: You've previously run `npm run build` which compiled @prpm/types to dist/. That compiled output exists in your node_modules. CI doesn't have this.
333 
334To test this scenario locally, delete your dist/ folders and try again:
335```bash
336rm -rf packages/*/dist
337npx tsc --noEmit  # Should fail
338npm run build --workspace=@prpm/types
339npx tsc --noEmit  # Should pass
340```
341 
342## Continuous Improvement
343 
344After each workflow failure in CI:
345 
3461. **Analyze**: Why didn't local testing catch this?
3472. **Document**: Add to the common failure patterns
3483. **Validate**: Update validation scripts to catch it next time
3494. **Test**: Ensure the validator actually catches the issue
350 
351## Best Practices
352 
3531. **Always validate before pushing**: Run the complete validation suite
3542. **Keep tools updated**: `brew upgrade act actionlint yamllint`
3553. **Test in clean environment occasionally**: Use Docker to simulate fresh CI
3564. **Document failures**: Add new patterns to validation scripts
3575. **Use explicit configurations**: Never rely on defaults for cache, paths, or commands
358 
359## Summary
360 
361This skill helps you:
362- ✅ Catch 90%+ of workflow failures before pushing
363- ✅ Understand why local testing didn't catch issues
364- ✅ Fix common GitHub Actions problems quickly
365- ✅ Build confidence in your CI/CD pipeline
366- ✅ Reduce iteration time (no more push-fail-fix-push cycles)
367 
368Invoke me whenever you're working with GitHub Actions to ensure your workflows are solid before they hit CI.
369