Skip to content

Commit 3962dda

Browse files
eszmweszmw
committed
feat: modernize GitHub Actions CI to use buildtool
1 parent 829ac2a commit 3962dda

1 file changed

Lines changed: 123 additions & 68 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 123 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,57 @@
1-
name: MATLAB Build
1+
name: MATLAB CI and Pages
22

3-
# Controls when the action will run.
3+
# WORKFLOW OVERVIEW
4+
# ==================
5+
# This workflow implements a multi-release MATLAB testing and documentation pipeline.
6+
# It tests courseware code across multiple MATLAB releases in parallel, validates results,
7+
# generates a status badge, and deploys documentation to GitHub Pages.
8+
#
9+
# ARCHITECTURE:
10+
# Phase 1 - test-matrix (parallel): Run tests independently for each MATLAB release
11+
# Phase 2 - report-and-deploy (sequential): Merge artifacts, validate, generate badge, deploy
12+
#
13+
# KEY FILES:
14+
# - buildfile.m : Defines build tasks (testing, validation, badge generation)
15+
# - SoftwareTests/CoursewareSmokeTests.m : Tests core courseware scripts
16+
# - SoftwareTests/FunctionTests.m : Placeholder for development function tests
17+
# - SoftwareTests/CrossReleaseTestResults.m : Validates all releases passed (gate for badge)
18+
#
19+
# ARTIFACT FLOW:
20+
# 1. test-matrix job (runs for each MATLAB release R2025a, R2025b):
21+
# $ buildtool test
22+
# -> public/R2025a/CoursewareSmokeTests.mat, FunctionTests.mat, etc.
23+
# -> Upload artifacts: test-results-R2025a, test-results-R2025b
24+
#
25+
# 2. report-and-deploy job (runs once, after test-matrix completes):
26+
# $ Download and merge all test-results-* artifacts into public/
27+
# $ buildtool report (runs report:validate, report:badge, report:link tasks)
28+
# -> SoftwareTests/CrossReleaseTestResults.m validates all releases passed
29+
# -> createBadge() generates public/TestedWith.json (shields.io format)
30+
# -> linkResultArtifactPathsInReportIndex() wraps test result links in HTML
31+
# -> Deploy public/ to GitHub Pages
32+
#
33+
# CUSTOMIZATION:
34+
# To change tested MATLAB releases: Edit matrix.Releases list (line 29)
35+
# To add/remove products: Edit MATLAB_PRODUCTS env variable (line 28)
36+
# To change deploy trigger: Edit 'on' workflow events (lines 3-7)
37+
#
38+
# FOR YOUR OWN COURSEWARE:
39+
# 1. Copy buildfile.m and SoftwareTests/ structure to your repo
40+
# 2. Create SoftwareTests/CoursewareSmokeTests.m with your own test suite
41+
# (reference: https://www.mathworks.com/help/matlab/matlab_prog/write-simple-test-suite.html)
42+
# 3. Update .github/workflows/ci.yml with your product list and release matrix
43+
# 4. Push to your release branch and monitor GitHub Actions
44+
#
45+
# TROUBLESHOOTING:
46+
# If tests fail in CI but pass locally:
47+
# - Check version(-release) output matches your installed MATLAB
48+
# - Verify all dependencies (products) are listed in MATLAB_PRODUCTS
49+
# - Review public/index.html report for detailed test output
50+
# If badge generation fails:
51+
# - Ensure SoftwareTests/CrossReleaseTestResults.m can find all release artifacts
52+
# - Check public/CrossReleaseTestResults.mat for missing or empty result variables
53+
54+
# Controls when the action will run.
455
on:
556
push:
657
branches: [ release ]
@@ -14,92 +65,108 @@ permissions:
1465
pages: write
1566
id-token: write
1667

68+
# Cancel older in-progress runs on the same ref to save CI time.
69+
concurrency:
70+
group: ${{ github.workflow }}-${{ github.ref }}
71+
cancel-in-progress: true
72+
1773
jobs:
18-
test:
19-
strategy:
74+
test-matrix:
75+
name: Test on ${{ matrix.Releases }}
76+
strategy:
2077
fail-fast: false
2178
matrix:
22-
MATLABVersion: [R2024b,R2025a,R2025b]
79+
Releases: [R2025b, R2026a]
2380
runs-on: ubuntu-latest
2481
env:
82+
MATLAB_PRODUCTS: >
83+
Symbolic_Math_Toolbox
84+
Statistics_and_Machine_Learning_Toolbox
85+
Partial_Differential_Equation_Toolbox
2586
LD_PRELOAD: /usr/lib/x86_64-linux-gnu/libstdc++.so.6
2687
steps:
2788
# Checks-out your repository
28-
- uses: actions/checkout@v4
29-
89+
- uses: actions/checkout@v6
90+
3091
# Sets up a display server
3192
- name: Start display server
3293
if: ${{ always() }}
3394
run: |
34-
sudo apt-get install xvfb
95+
sudo apt-get update
96+
sudo apt-get install -y xvfb
3597
Xvfb :99 &
3698
echo "DISPLAY=:99" >> $GITHUB_ENV
37-
99+
38100
# Sets up MATLAB
39-
- name: Setup MATLAB
40-
uses: matlab-actions/setup-matlab@v2
101+
- name: Setup MATLAB ${{ matrix.Releases }}
102+
uses: matlab-actions/setup-matlab@v3
41103
with:
42-
release: ${{ matrix.MATLABVersion }}
43-
products: >
44-
Symbolic_Math_Toolbox
45-
Partial_Differential_Equation_Toolbox
46-
Statistics_and_Machine_Learning_Toolbox
47-
# Simulink Statistics_and_Machine_Learning_Toolbox
48-
# List required products above in the format shown (and uncomment them)
49-
# List of product strings:
50-
# Simulink
51-
# Statistics_and_Machine_Learning_Toolbox
52-
# Simulink_Coder
53-
# Econometrics_Toolbox
54-
# Deep_Learning_Toolbox
55-
56-
57-
# Run all the tests
58-
- name: Run SmokeTests
59-
uses: matlab-actions/run-command@v2
104+
release: ${{ matrix.Releases }}
105+
products: ${{ env.MATLAB_PRODUCTS }}
106+
cache: true
107+
108+
# Run aggregated test task from buildfile.m.
109+
- name: Run buildtool test
110+
uses: matlab-actions/run-build@v3
60111
with:
61-
command: openProject(pwd); RunAllTests;
112+
tasks: test
113+
build-options: -continueOnFailure
62114

63-
# Upload the test results as artifact
64-
- name: Upload TestResults
115+
# Upload only files required by buildtool report/pages to reduce artifact size.
116+
- name: Upload test results artifact
65117
if: ${{ always() }}
66-
uses: actions/upload-artifact@v4
118+
uses: actions/upload-artifact@v6
67119
with:
68-
name: TestResults_${{ matrix.MATLABVersion }}
69-
path: ./public/*
120+
name: ${{ matrix.Releases }}
121+
path: |
122+
./public/${{ matrix.Releases }}/
70123
overwrite: true
124+
retention-days: 7
71125

72-
badge:
126+
report-and-deploy:
127+
name: Build badge and deploy reports
73128
if: ${{ always() }}
74-
needs: [test]
75-
strategy:
76-
fail-fast: false
129+
needs: [test-matrix]
77130
runs-on: ubuntu-latest
78-
steps:
131+
steps:
79132

80133
# Checks-out your repository
81-
- uses: actions/checkout@v4
82-
83-
# Sets up R2023b
84-
- name: Setup MATLAB
85-
uses: matlab-actions/setup-matlab@v2
134+
- uses: actions/checkout@v6
135+
136+
# GitHub-hosted jobs are isolated; MATLAB install from test-matrix cannot be reused here.
137+
# Keep this setup minimal (no extra products) and use artifacts from matrix jobs.
138+
139+
# Sets latest MATLAB for report task (no toolbox list needed).
140+
- name: Setup MATLAB latest
141+
uses: matlab-actions/setup-matlab@v3
86142
with:
87-
release: R2024b
88-
143+
release: latest
144+
cache: true
145+
89146
# Download the test results from artifact
90147
- name: Download All TestResults
91-
uses: actions/download-artifact@v4
148+
uses: actions/download-artifact@v8
92149
with:
93150
path: public
94-
pattern: TestResults_*
95-
merge-multiple: true
96-
97-
# Create the test results badge
98-
- name: Run PostSmokeTest
99-
uses: matlab-actions/run-command@v2
151+
pattern: R20*
152+
merge-multiple: false
153+
154+
# Aggregate test reports and generate badge via buildfile.
155+
- name: Run buildtool report
156+
uses: matlab-actions/run-build@v3
157+
with:
158+
tasks: report
159+
build-options: -continueOnFailure
160+
161+
# Upload the badge as artifact
162+
- name: Upload Badge
163+
if: ${{ always() }}
164+
uses: actions/upload-artifact@v6
100165
with:
101-
command: openProject(pwd); PostSmokeTest;
102-
166+
name: Badge-Artifact
167+
path: ./public/TestedWith.json
168+
overwrite: true
169+
103170
# Deploy reports to GitHub pages
104171
- name: Setup Pages
105172
uses: actions/configure-pages@v5
@@ -110,15 +177,3 @@ jobs:
110177
- name: Deploy to GitHub Pages
111178
id: deployment
112179
uses: actions/deploy-pages@v4
113-
114-
# Commit the JSON for the MATLAB releases badge
115-
- name: Commit changed files
116-
continue-on-error: true
117-
run: |
118-
git config user.name "${{ github.workflow }} by ${{ github.actor }}"
119-
git config user.email "<>"
120-
git pull
121-
git add Images/TestedWith.json
122-
git commit Images/TestedWith.json -m "Update CI badges ${{ github.ref_name }}"
123-
git fetch
124-
git push

0 commit comments

Comments
 (0)