81.2 Project 78: Matrix builds across versions
Friends, one Node version is not enough. Today we add a strategy matrix for Node 18 and 20, fail-fast carefully, and read which cell broke.
मित्रांनो, एक Node version पुरेसे नाही. आज Node 18 आणि 20 साठी strategy matrix, fail-fast, आणि कोणता cell फुटला ते वाचा.
दोस्तों, एक Node version काफी नहीं. आज Node 18 और 20 के लिए strategy matrix, fail-fast, और कौन सा cell टूटा पढ़ें.
What you will build in this project
- Add strategy.matrix for Node versions.
- Use matrix.node in setup-node.
- Tune fail-fast.
- Read the matrix summary.
1. Start from a real company story
At Zoho in Chennai, CI tested only Node 18 while prod ran 20 and optional chaining crashed at peak.
Rough cost: about ₹14 lakh in error budgets that day.
Hari added a matrix for 18 and 20 on every PR.
Today we build that matrix.
Ravindra Bagale's Tip
Students set fail-fast true and miss the second version failure. Prefer fail-fast false while debugging. Keep that habit.
Students fail-fast true ठेवतात आणि दुसरी version failure चुकवतात. Debug करताना false ठेवा. सवय ठेवा.
Students fail-fast true रखते हैं और दूसरी version failure चूक जाते हैं. Debug में false रखें. आदत रखिए.
2. Start and prepare
Step 1: Why matrix
Why: Prod may differ from laptop. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: echo why. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 1: a1
Type this:
echo 'Matrix = one job template expanded into many versions'
You will see:
Matrix = one job template expanded into many versions
What it means: Why.
Example 2: a2
Type this:
mkdir -p /tmp/gha78/.github/workflows && echo 'Today: matrix node 18/20, fail-fast, summary'
You will see:
Today: matrix node 18/20, fail-fast, summary
What it means: Scope.
Example 3: a3
Type this:
echo 'Always include the production Node major'
You will see:
Always include the production Node major
What it means: Rule.
Step 2: Matrix YAML
Why: strategy block. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: printf. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 4: b1
Type this:
printf '%s\n' 'name: matrix-ci' 'on: [push, pull_request]' 'jobs:' ' test:' ' runs-on: ubuntu-latest' ' strategy:' ' fail-fast: false' ' matrix:' ' node: [18, 20]' ' steps:' ' - uses: actions/checkout@v4' ' - uses: actions/setup-node@v4' ' with:' ' node-version: ${{ matrix.node }}' ' cache: npm' ' - run: npm ci' ' - run: npm test' > /tmp/gha78/.github/workflows/matrix.yml && grep -A2 matrix: /tmp/gha78/.github/workflows/matrix.yml
You will see:
matrix:\n node: [18, 20]
What it means: Matrix.
Example 5: b2
Type this:
echo 'matrix.node is referenced as \${{ matrix.node }}'
You will see:
matrix.node is referenced as ${{ matrix.node }}
What it means: Expr.
Example 6: b3
Type this:
wc -l /tmp/gha78/.github/workflows/matrix.yml
You will see:
18 /tmp/gha78/.github/workflows/matrix.yml
What it means: Lines.
Step 3: fail-fast
Why: When to stop siblings. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: tune. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 7: c1
Type this:
echo 'fail-fast true cancels other cells when one fails'
You will see:
fail-fast true cancels other cells when one fails
What it means: True.
Example 8: c2
Type this:
echo 'fail-fast false lets every cell finish — better for first debug'
You will see:
fail-fast false lets every cell finish — better for first debug
What it means: False.
Example 9: c3
Type this:
printf '%s\n' 'Use true later to save minutes once the suite is stable' > /tmp/gha78/FAILFAST.txt && cat /tmp/gha78/FAILFAST.txt
You will see:
Use true later to save minutes once the suite is stable
What it means: Later.
3. Build the main pieces
Step 4: OS matrix tip
Why: Optional expand. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: os list. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 10: d1
Type this:
printf '%s\n' 'matrix:' ' node: [18, 20]' ' os: [ubuntu-latest, windows-latest]' 'runs-on: \${{ matrix.os }}' > /tmp/gha78/OS.txt && cat /tmp/gha78/OS.txt
You will see:
os: [ubuntu-latest, windows-latest]
What it means: OS.
Example 11: d2
Type this:
echo 'Two nodes times two OS = four jobs — watch minutes'
You will see:
Two nodes times two OS = four jobs — watch minutes
What it means: Cost.
Example 12: d3
Type this:
echo 'Start with Node-only matrix; add OS when you ship Windows clients'
You will see:
Start with Node-only matrix; add OS when you ship Windows clients
What it means: Order.
Step 5: Exclude include
Why: Trim cells. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: exclude. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 13: e1
Type this:
printf '%s\n' 'exclude:' ' - node: 18' ' os: windows-latest' > /tmp/gha78/EXCLUDE.txt && cat /tmp/gha78/EXCLUDE.txt
You will see:
exclude:
What it means: Exclude.
Example 14: e2
Type this:
echo 'include can add a special cell like node 22 experimental'
You will see:
include can add a special cell like node 22 experimental
What it means: Include.
Example 15: e3
Type this:
echo 'Mark experimental cells continue-on-error true'
You will see:
Mark experimental cells continue-on-error true
What it means: Experimental.
Step 6: Read summary
Why: Which cell failed. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: UI tip. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 16: f1
Type this:
printf '%s\n' 'Actions run page lists each matrix cell as a job' 'Name shows test (18) and test (20)' 'Open the red cell first' > /tmp/gha78/SUMMARY.txt && cat /tmp/gha78/SUMMARY.txt
You will see:
Name shows test (18) and test (20)
What it means: Summary.
Example 17: f2
Type this:
echo 'Job name can use matrix values: test-node-\${{ matrix.node }}'
You will see:
Job name can use matrix values: test-node-${{ matrix.node }}
What it means: Name.
Example 18: f3
Type this:
printf '%s\n' 'Acceptance: both 18 and 20 green' > /tmp/gha78/ACCEPT.txt && cat /tmp/gha78/ACCEPT.txt
You will see:
Acceptance: both 18 and 20 green
What it means: Gate.
4. Automate and verify
Step 7: Local tip
Why: nvm or fnm. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: laptop. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 19: g1
Type this:
echo 'fnm use 18 && npm test && fnm use 20 && npm test'
You will see:
fnm use 18 && npm test && fnm use 20 && npm test
What it means: Local.
Example 20: g2
Type this:
echo 'Catch version bugs before you push'
You will see:
Catch version bugs before you push
What it means: Habit.
Example 21: g3
Type this:
echo 'engines field in package.json documents the range'
You will see:
engines field in package.json documents the range
What it means: engines.
Step 8: Minutes budget
Why: Hosted runners cost. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: watch usage. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 22: h1
Type this:
printf '%s\n' 'Org Settings -> Billing -> Actions minutes' 'Matrix doubles minutes — keep tests fast' > /tmp/gha78/MINUTES.txt && cat /tmp/gha78/MINUTES.txt
You will see:
Matrix doubles minutes — keep tests fast
What it means: Minutes.
Example 23: h2
Type this:
echo 'Self-hosted runners help heavy matrices later'
You will see:
Self-hosted runners help heavy matrices later
What it means: Self-hosted.
Example 24: h3
Type this:
echo 'Cache npm to cut install time on every cell'
You will see:
Cache npm to cut install time on every cell
What it means: Cache.
Step 9: Prod alignment
Why: Matrix must cover prod. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: rule. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 25: i1
Type this:
echo 'If prod is Node 20, matrix must include 20'
You will see:
If prod is Node 20, matrix must include 20
What it means: Rule.
Example 26: i2
Type this:
echo 'Drop Node 16 only after prod and all services moved'
You will see:
Drop Node 16 only after prod and all services moved
What it means: Drop.
Example 27: i3
Type this:
echo 'Document the supported majors in CONTRIBUTING notes'
You will see:
Document the supported majors in CONTRIBUTING notes
What it means: Docs.
5. Harden and accept
Step 10: Story Zoho
Why: Chennai version gap. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: story. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 28: j1
Type this:
printf '%s\n' 'At Zoho in Chennai, CI tested Node 18 while prod ran 20 and optional chaining crashed.' 'Hari added a matrix for 18 and 20 on every PR.' > /tmp/gha78/STORY.txt && wc -l /tmp/gha78/STORY.txt
You will see:
2 /tmp/gha78/STORY.txt
What it means: Story.
Example 29: j2
Type this:
echo 'Rough cost: about ₹14 lakh in error budgets that day'
You will see:
Rough cost: about ₹14 lakh in error budgets that day
What it means: Cost.
Example 30: j3
Type this:
echo 'Hari: PASS'
You will see:
Hari: PASS
What it means: Sign-off.
Step 11: Proof
Why: YAML has matrix. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: grep. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 31: k1
Type this:
grep -A3 'matrix:' /tmp/gha78/.github/workflows/matrix.yml
You will see:
matrix:\n node: [18, 20]\n steps:\n - uses: actions/checkout@v4
What it means: Matrix block.
Example 32: k2
Type this:
grep fail-fast /tmp/gha78/.github/workflows/matrix.yml
You will see:
fail-fast: false
What it means: fail-fast.
Example 33: k3
Type this:
echo 'Next: Docker build and push with Actions project 79'
You will see:
Next: Docker build and push with Actions project 79
What it means: Bridge.
Step 12: Acceptance
Why: Both cells green. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.
What: final. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.
Example 34: z1
Type this:
echo 'matrix node 18 and 20'
You will see:
matrix node 18 and 20
What it means: Matrix.
Example 35: z2
Type this:
echo 'fail-fast false while learning'
You will see:
fail-fast false while learning
What it means: Fail-fast.
Example 36: z3
Type this:
echo 'Prod major included'
You will see:
Prod major included
What it means: Prod.
Check yourself
Q1. Who fixed Zoho Node gap?
Hari
Q2. Key word?
matrix
Q3. Versions example?
18 and 20
Q4. setup input?
node-version
Q5. fail-fast debug?
false
Q6. Prod must be in matrix?
yes
Friends, you ran a Node version matrix. Did you understand? Let us try it once more. Add node 22 to the matrix and prove three cells run.
मित्रांनो, तुम्ही Node version matrix चालवली. Matrix मध्ये node 22 जोडा आणि तीन cells चालतात हे सिद्ध करा.
दोस्तों, आपने Node version matrix चलाई. Matrix में node 22 जोड़ें और तीन cells चलें, यह साबित करें.
Lab: try at home
- Edit matrix.
- Wire node-version.
- Set fail-fast.
- Read summary.
Recap
- Matrix multiplies jobs.
- Pin each cell.
- fail-fast false while learning.
- Summary shows the broken cell.
- Prod version must be in the matrix.