Cursor rule

1---
2description: GitHub Actions Workflow Rules
3globs: [".github/workflows/*.yml"]
4alwaysApply: false
5---
6 
7 
8# GitHub Actions Workflow Rules
9 
10## Overview
11 
12Rules for modifying GitHub Actions workflow files (`.github/workflows/*.yml`) in go-crypto-wallet.
13 
14## Runner Configuration
15 
16### Required Runner
17 
18**Always use `ubuntu-slim` as the runner** unless there is a specific reason to use another image.
19 
20```yaml
21# Good
22runs-on: ubuntu-slim
23 
24# Avoid (unless specifically needed)
25runs-on: ubuntu-latest
26runs-on: ubuntu-24.04
27```
28 
29### Why ubuntu-slim?
30 
31- Faster startup time (smaller image)
32- Lower resource consumption
33- Contains essential tools for most CI tasks
34- Cost-effective for GitHub Actions minutes
35 
36Reference: [GitHub Actions Runner Images](https://github.com/actions/runner-images)
37 
38### Available Runners
39 
40| Image | YAML Label | Use Case |
41|-------|------------|----------|
42| Ubuntu Slim | `ubuntu-slim` | **Default choice** - most CI tasks |
43| Ubuntu 24.04 | `ubuntu-latest` or `ubuntu-24.04` | When additional tools are required |
44| Ubuntu 22.04 | `ubuntu-22.04` | Legacy compatibility |
45 
46## Performance Best Practices
47 
48### Avoid Duplication
49 
501. **Reusable Workflows**: Extract common patterns into reusable workflows
512. **Composite Actions**: Create composite actions for repeated steps
523. **Matrix Strategy**: Use matrix for parallel execution instead of duplicate jobs
53 
54```yaml
55# Good: Matrix strategy for parallel execution
56strategy:
57  matrix:
58    go-version: ['1.22', '1.23']
59 
60# Avoid: Duplicate jobs for each version
61jobs:
62  test-go-122:
63    ...
64  test-go-123:
65    ...
66```
67 
68### Caching
69 
70Always use caching for dependencies:
71 
72```yaml
73- uses: actions/cache@v4
74  with:
75    path: |
76      ~/.cache/go-build
77      ~/go/pkg/mod
78    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
79```
80 
81### Conditional Execution
82 
83Use path filters to avoid unnecessary runs:
84 
85```yaml
86on:
87  push:
88    paths:
89      - '**.go'
90      - 'go.mod'
91      - 'go.sum'
92```
93 
94## Branch Configuration
95 
96### Default Branch
97 
98This repository uses `main` as the default branch. Always use `main` (not `master`):
99 
100```yaml
101# Good
102on:
103  push:
104    branches:
105      - main
106 
107# Wrong
108on:
109  push:
110    branches:
111      - master
112```
113 
114## Workflow Structure
115 
116### Standard Workflow Template
117 
118```yaml
119name: Workflow Name
120
121on:
122  push:
123    branches:
124      - main
125    paths:
126      - 'relevant/paths/**'
127  pull_request:
128    branches:
129      - main
130  workflow_dispatch:  # Manual trigger
131
132jobs:
133  job-name:
134    name: Descriptive Job Name
135    runs-on: ubuntu-slim
136    timeout-minutes: 10  # Always set timeout
137    permissions:
138      contents: read     # Minimal permissions
139    steps:
140      - uses: actions/checkout@v6
141      # ... steps
142```
143 
144### Required Elements
145 
146| Element | Required | Description |
147|---------|----------|-------------|
148| `timeout-minutes` | Yes | Prevent runaway jobs |
149| `permissions` | Yes | Principle of least privilege |
150| `runs-on: ubuntu-slim` | Yes | Standard runner |
151 
152## Verification
153 
154Before committing workflow changes:
155 
1561. Validate YAML syntax
1572. Check for branch name (`main` not `master`)
1583. Verify runner is `ubuntu-slim`
1594. Ensure timeout is set
1605. Review permissions (minimal required)
161 
162```bash
163# Validate YAML syntax
164make yaml-lint
165```
166 
167## Quick Checklist
168 
169- [ ] Runner is `ubuntu-slim`
170- [ ] Branch is `main` (not `master`)
171- [ ] `timeout-minutes` is set
172- [ ] `permissions` block is defined
173- [ ] Path filters are used where appropriate
174- [ ] Caching is implemented for dependencies
175- [ ] No duplicate jobs (use matrix instead)
176 
177## Related Documentation
178 
179- @.github/workflows/ - Existing workflows
180- @.github/labels.yml - Repository labels
181 
182## Related Skills
183 
184- `devops` - CI/CD and DevOps workflow
185