Skip to content

Commit 52a230d

Browse files
pepicrftpepicrft
authored
Merge pull request #6 from tuist/feat/matrix-strategy-support
feat: Add matrix strategy support for GitHub Actions
2 parents 3efb50b + 68b0d89 commit 52a230d

3 files changed

Lines changed: 812 additions & 11 deletions

File tree

‎CLAUDE.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,12 @@ Magnolia is a Rust CLI tool that enables developers to run GitLab CI, GitHub Act
1313
2. **CI System Modules**:
1414
- `src/gitlab.rs`: Parses and executes GitLab CI pipelines (.gitlab-ci.yml)
1515
- `src/github.rs`: Parses and executes GitHub Actions workflows (.github/workflows/*.yml)
16+
- Supports matrix strategy expansion (v0.3.0+)
17+
- Matrix interpolation in runs-on, step names, and commands
18+
- Support for fail-fast and max-parallel options
1619
- `src/forgejo.rs`: Parses and executes Forgejo/Gitea Actions workflows (.forgejo/workflows/*.yml or .gitea/workflows/*.yml)
20+
- `src/container.rs`: Container runtime detection and execution (Docker/Podman)
21+
- `src/actions.rs`: GitHub Actions execution support
1722

1823
### Commands
1924

@@ -52,15 +57,9 @@ The project uses `git-cliff` for changelog generation and semantic versioning. T
5257
3. Test: `mise exec -- cargo test`
5358
4. Run locally: `mise exec -- cargo run -- <command>`
5459

55-
## Future Enhancements
60+
## Feature Development
5661

57-
- Actual job execution (currently in simulation mode)
58-
- Docker container support for isolated execution
59-
- Environment variable handling
60-
- Secret management
61-
- Parallel job execution
62-
- Job dependency resolution
63-
- Cache support
62+
For the complete feature roadmap, implementation priorities, and detailed technical specifications, see [PLAN.md](PLAN.md).
6463

6564
## Testing the CLI
6665

‎PLAN.md‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
# Magnolia Feature Roadmap
2+
3+
This document outlines the planned features and enhancements for Magnolia, prioritized based on usage frequency in real-world GitHub Actions workflows.
4+
5+
## Completed Features
6+
7+
### Matrix Strategies ✅
8+
- **Status**: Implemented in v0.3.0+
9+
- **Description**: Support for `strategy.matrix` to run jobs across multiple configurations
10+
- **Features**:
11+
- Multi-dimensional matrix expansion (e.g., `os x rust-version`)
12+
- Matrix value interpolation in `runs-on`, step names, and commands
13+
- Support for `fail-fast` and `max-parallel` strategy options
14+
- Comprehensive unit tests for matrix expansion and interpolation
15+
- **Location**: `src/github.rs:9-86`
16+
17+
## High Priority Features
18+
19+
### 1. Environment Variables
20+
**Priority**: P0 - Critical
21+
**Complexity**: Medium
22+
**Impact**: Required by nearly all workflows
23+
24+
**Description**: Support for environment variables at workflow, job, and step levels.
25+
26+
**Implementation Tasks**:
27+
- [ ] Add `env` field to `GitHubWorkflow`, `Job`, and `Step` structs
28+
- [ ] Implement environment variable interpolation (`${{ env.* }}`)
29+
- [ ] Support for `.env` file loading
30+
- [ ] Merge env vars from workflow → job → step (most specific wins)
31+
- [ ] Pass environment variables to container and host execution
32+
33+
**Example**:
34+
```yaml
35+
env:
36+
GLOBAL_VAR: "value"
37+
38+
jobs:
39+
build:
40+
env:
41+
JOB_VAR: "value"
42+
steps:
43+
- name: Test
44+
env:
45+
STEP_VAR: "value"
46+
run: echo $STEP_VAR
47+
```
48+
49+
**Architecture Considerations**:
50+
- Create `EnvContext` struct to manage variable resolution
51+
- Implement variable precedence rules (step > job > workflow)
52+
- Support both `${{ env.VAR }}` and `$VAR` syntax
53+
54+
---
55+
56+
### 2. Caching Support
57+
**Priority**: P0 - Critical
58+
**Complexity**: High
59+
**Impact**: Dramatically improves workflow performance
60+
61+
**Description**: Support for `actions/cache` and similar caching actions.
62+
63+
**Implementation Tasks**:
64+
- [ ] Implement cache key generation (support for hashFiles function)
65+
- [ ] Create local cache storage (e.g., `~/.magnolia/cache/`)
66+
- [ ] Add cache hit/miss detection
67+
- [ ] Support for cache restore and save operations
68+
- [ ] Implement cache size limits and LRU eviction
69+
- [ ] Support for `actions/cache@v4` and `Swatinem/rust-cache@v2`
70+
71+
**Example**:
72+
```yaml
73+
- uses: actions/cache@v4
74+
with:
75+
path: target
76+
key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
77+
```
78+
79+
**Architecture Considerations**:
80+
- Design pluggable cache backend (filesystem, Redis, etc.)
81+
- Implement cache key hashing with support for `hashFiles()`
82+
- Consider cache compression to save disk space
83+
84+
---
85+
86+
### 3. Job Dependencies (`needs`)
87+
**Priority**: P0 - Critical
88+
**Complexity**: Medium
89+
**Impact**: Required for complex pipelines
90+
91+
**Description**: Support for job dependencies and execution ordering.
92+
93+
**Implementation Tasks**:
94+
- [ ] Add `needs` field to `Job` struct
95+
- [ ] Implement dependency graph resolution
96+
- [ ] Add cycle detection for circular dependencies
97+
- [ ] Support for parallel job execution
98+
- [ ] Handle job failure propagation with `fail-fast`
99+
- [ ] Update job selection UI to show dependency tree
100+
101+
**Example**:
102+
```yaml
103+
jobs:
104+
build:
105+
runs-on: ubuntu-latest
106+
steps: [...]
107+
108+
test:
109+
needs: build
110+
runs-on: ubuntu-latest
111+
steps: [...]
112+
```
113+
114+
**Architecture Considerations**:
115+
- Use topological sort for dependency resolution
116+
- Implement async job execution with tokio
117+
- Create job status tracking for dependent jobs
118+
119+
---
120+
121+
### 4. Conditional Execution (`if`)
122+
**Priority**: P1 - High
123+
**Complexity**: High
124+
**Impact**: Common pattern for workflow control
125+
126+
**Description**: Support for conditional job and step execution.
127+
128+
**Implementation Tasks**:
129+
- [ ] Add `if` field to `Job` and `Step` structs
130+
- [ ] Implement expression evaluator for GitHub Actions expressions
131+
- [ ] Support for contexts: `github`, `env`, `matrix`, `needs`, etc.
132+
- [ ] Support for common functions: `contains()`, `startsWith()`, `endsWith()`, etc.
133+
- [ ] Handle boolean operators: `&&`, `||`, `!`
134+
- [ ] Skip execution when condition evaluates to false
135+
136+
**Example**:
137+
```yaml
138+
jobs:
139+
test:
140+
if: github.event_name == 'pull_request'
141+
steps:
142+
- name: Deploy
143+
if: success() && github.ref == 'refs/heads/main'
144+
run: ./deploy.sh
145+
```
146+
147+
**Architecture Considerations**:
148+
- Create expression parser (consider using pest or nom)
149+
- Implement context providers for different scopes
150+
- Cache expression evaluation results
151+
152+
---
153+
154+
### 5. Context Expression Evaluation
155+
**Priority**: P1 - High
156+
**Complexity**: High
157+
**Impact**: Enables dynamic workflows
158+
159+
**Description**: Full support for GitHub Actions context expressions.
160+
161+
**Implementation Tasks**:
162+
- [ ] Implement `${{ github.* }}` context (event, ref, sha, actor, etc.)
163+
- [ ] Implement `${{ runner.* }}` context (os, arch, temp, workspace)
164+
- [ ] Implement `${{ job.* }}` context (status, container)
165+
- [ ] Implement `${{ steps.* }}` context (outputs, outcome, conclusion)
166+
- [ ] Support for `${{ needs.* }}` context (outputs from dependent jobs)
167+
- [ ] Implement built-in functions (fromJSON, toJSON, format, join, etc.)
168+
169+
**Example**:
170+
```yaml
171+
- name: Print context
172+
run: echo "Branch is ${{ github.ref }}"
173+
```
174+
175+
**Architecture Considerations**:
176+
- Create unified context system with all available data
177+
- Implement lazy evaluation for performance
178+
- Add comprehensive function library
179+
180+
---
181+
182+
### 6. Artifact Upload/Download
183+
**Priority**: P1 - High
184+
**Complexity**: Medium
185+
**Impact**: Common pattern for build artifacts
186+
187+
**Description**: Full support for artifact actions.
188+
189+
**Implementation Tasks**:
190+
- [ ] Implement `actions/upload-artifact@v4` support
191+
- [ ] Implement `actions/download-artifact@v4` support
192+
- [ ] Create local artifact storage (e.g., `~/.magnolia/artifacts/`)
193+
- [ ] Support for artifact retention and cleanup
194+
- [ ] Handle artifact path patterns and compression
195+
- [ ] Support artifact sharing between jobs
196+
197+
**Example**:
198+
```yaml
199+
- uses: actions/upload-artifact@v4
200+
with:
201+
name: build-output
202+
path: target/release/
203+
```
204+
205+
**Architecture Considerations**:
206+
- Design artifact metadata storage (JSON index)
207+
- Implement efficient compression (tar.gz)
208+
- Consider artifact size limits
209+
210+
---
211+
212+
## Medium Priority Features
213+
214+
### 7. Improved Action Execution
215+
**Priority**: P2 - Medium
216+
**Complexity**: High
217+
**Impact**: Better third-party action support
218+
219+
**Implementation Tasks**:
220+
- [ ] Parse action.yml from action repositories
221+
- [ ] Support for Docker container actions
222+
- [ ] Support for JavaScript actions (via Node.js)
223+
- [ ] Support for composite actions
224+
- [ ] Implement action input/output handling
225+
- [ ] Clone actions from GitHub when needed
226+
227+
---
228+
229+
### 8. Secrets Management
230+
**Priority**: P2 - Medium
231+
**Complexity**: Medium
232+
**Impact**: Required for production workflows
233+
234+
**Implementation Tasks**:
235+
- [ ] Design secure secrets storage (keychain integration)
236+
- [ ] Implement `${{ secrets.* }}` interpolation
237+
- [ ] Add CLI commands to manage secrets
238+
- [ ] Support for `.env` file integration
239+
- [ ] Mask secret values in output logs
240+
241+
---
242+
243+
### 9. Service Containers
244+
**Priority**: P2 - Medium
245+
**Complexity**: High
246+
**Impact**: Required for integration tests
247+
248+
**Implementation Tasks**:
249+
- [ ] Add `services` field to `Job` struct
250+
- [ ] Start service containers before job execution
251+
- [ ] Configure service networking (ports, healthchecks)
252+
- [ ] Clean up services after job completion
253+
- [ ] Support for service credentials and env vars
254+
255+
---
256+
257+
### 10. Reusable Workflows
258+
**Priority**: P2 - Medium
259+
**Complexity**: High
260+
**Impact**: Code reuse across workflows
261+
262+
**Implementation Tasks**:
263+
- [ ] Support for `workflow_call` trigger
264+
- [ ] Implement workflow input parameters
265+
- [ ] Support for workflow outputs
266+
- [ ] Handle nested workflow execution
267+
- [ ] Implement workflow limits (max 10 nested)
268+
269+
---
270+
271+
## Lower Priority Features
272+
273+
### 11. Workflow Dispatch
274+
**Priority**: P3 - Low
275+
**Complexity**: Medium
276+
277+
**Implementation Tasks**:
278+
- [ ] Support for `workflow_dispatch` trigger
279+
- [ ] Implement input parameters via CLI
280+
- [ ] Support for input types (string, choice, boolean)
281+
282+
---
283+
284+
### 12. Parallel Execution
285+
**Priority**: P3 - Low
286+
**Complexity**: High
287+
288+
**Implementation Tasks**:
289+
- [ ] Implement concurrent job execution
290+
- [ ] Support for `max-parallel` limits
291+
- [ ] Resource-aware scheduling
292+
293+
---
294+
295+
### 13. Path/Branch Filters
296+
**Priority**: P3 - Low
297+
**Complexity**: Low
298+
299+
**Implementation Tasks**:
300+
- [ ] Parse `on.push.paths` and `on.pull_request.paths`
301+
- [ ] Implement glob pattern matching
302+
- [ ] Support for branch patterns
303+
304+
---
305+
306+
## Testing Strategy
307+
308+
For each feature, implement:
309+
310+
1. **Unit Tests**: Test core logic in isolation
311+
2. **Integration Tests**: Test with real workflow files
312+
3. **Fixture Workflows**: Add example workflows to `fixtures/`
313+
4. **Documentation**: Update README and CLAUDE.md
314+
315+
## Design Principles
316+
317+
1. **Modularity**: Each feature should be self-contained
318+
2. **Testing**: Comprehensive tests before merging
319+
3. **Performance**: Lazy evaluation and caching where possible
320+
4. **Compatibility**: Match GitHub Actions behavior as closely as possible
321+
5. **Error Handling**: Clear, actionable error messages
322+
6. **Architecture**: Follow existing patterns in the codebase
323+
324+
## Contributing
325+
326+
When implementing features from this roadmap:
327+
328+
1. Create a feature branch: `feat/<feature-name>`
329+
2. Update this document with implementation notes
330+
3. Add comprehensive tests
331+
4. Update CLAUDE.md with architecture notes
332+
5. Create a PR with detailed description
333+
334+
## Version Planning
335+
336+
- **v0.4.0**: Environment Variables + Caching
337+
- **v0.5.0**: Job Dependencies + Conditional Execution
338+
- **v0.6.0**: Context Expressions + Artifacts
339+
- **v0.7.0**: Improved Actions + Secrets
340+
- **v0.8.0**: Service Containers + Reusable Workflows
341+
- **v1.0.0**: Production-ready with all high-priority features

0 commit comments

Comments
 (0)