Skip to content

Commit 52a880c

Browse files
guitarrapcguitarrapc
authored
Merge pull request #237 from guitarrapc/matrix
feat: add matrix
2 parents c725945 + f5ec12c commit 52a880c

5 files changed

Lines changed: 201 additions & 44 deletions

File tree

‎.github/workflows/matrix-envvar.yaml‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,7 @@ jobs:
1717
timeout-minutes: 3
1818
env:
1919
ORG: ${{ matrix.org }}
20-
# you can not use expression. do it on step.
21-
# output on step is -> ci-`date '+%Y%m%d-%H%M%S'`+${GITHUB_SHA:0:6}
22-
# GIT_TAG: "ci-`date '+%Y%m%d-%H%M%S'`+${GITHUB_SHA:0:6}"
20+
# you can not use expression inside env:. do it on step.
2321
steps:
2422
- run: echo "${ORG}"
2523
- run: echo "${NEW_ORG}"

‎.github/workflows/matrix-include-exclude.yaml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: matrix include exclude
2+
on:
3+
workflow_dispatch:
4+
push:
5+
branches: ["main"]
6+
pull_request:
7+
branches: ["main"]
8+
9+
jobs:
10+
echo:
11+
strategy:
12+
matrix:
13+
include:
14+
- fruit: apples
15+
- fruit: bananas
16+
- fruit: carrots
17+
exclude:
18+
- fruit: bananas
19+
permissions:
20+
contents: read
21+
runs-on: ubuntu-24.04
22+
timeout-minutes: 3
23+
steps:
24+
- run: echo "${matrix.fruit}"

‎.github/workflows/matrix-includesonly.yaml‎

Lines changed: 0 additions & 30 deletions
This file was deleted.

‎.github/workflows/matrix.yaml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: matrix
2+
on:
3+
workflow_dispatch:
4+
push:
5+
branches: ["main"]
6+
pull_request:
7+
branches: ["main"]
8+
9+
jobs:
10+
parallel:
11+
strategy:
12+
# If set true, then if one matrix job fails, cancel others
13+
fail-fast: false # default is true.
14+
matrix:
15+
version: [10, 12, 14]
16+
runs-on: [ubuntu-24.04, ubuntu-latest]
17+
permissions:
18+
contents: read
19+
runs-on: ${{ matrix.runs-on }}
20+
timeout-minutes: 3
21+
steps:
22+
- name: Show runner info
23+
run: |
24+
echo "runner.os: ${{ runner.os }}"
25+
echo "matrix.runs-on: ${{ matrix.runs-on }}"
26+
echo "matrix.version: ${{ matrix.version }}"
27+
28+
serial:
29+
strategy:
30+
# run matrix jobs one by one = serial execution
31+
max-parallel: 1
32+
matrix:
33+
version: [10, 12, 14]
34+
runs-on: [ubuntu-24.04, ubuntu-latest]
35+
permissions:
36+
contents: read
37+
runs-on: ${{ matrix.runs-on }}
38+
timeout-minutes: 3
39+
steps:
40+
- name: Show runner info
41+
run: |
42+
echo "runner.os: ${{ runner.os }}"
43+
echo "matrix.runs-on: ${{ matrix.runs-on }}"

‎README.md‎

Lines changed: 133 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,7 @@ GitHub Actions research and test laboratory.
5252
- [Run when previous job is success](#run-when-previous-job-is-success)
5353
- [Run when previous step status is specific](#run-when-previous-step-status-is-specific)
5454
- [Run write Multiline code](#run-write-multiline-code)
55-
- [Strategy matrix and secret dereference](#strategy-matrix-and-secret-dereference)
56-
- [Strategy matrix and environment variables](#strategy-matrix-and-environment-variables)
55+
- [Matrix](#matrix)
5756
- [Timeout settings](#timeout-settings)
5857
- [Workflow dispatch and passing input](#workflow-dispatch-and-passing-input)
5958
- [Workflow dispatch with mixed input type](#workflow-dispatch-with-mixed-input-type)
@@ -1782,11 +1781,68 @@ jobs:
17821781
17831782
```
17841783

1785-
## Strategy matrix and secret dereference
1784+
## Matrix
17861785

1787-
matrix cannot reference `secret` context, so pass secret key in matrix then dereference secret with `secrets[matrix.SECRET_KEY]`.
1786+
Matrix is useful when you want to run same job with different parameters like OS, version and so on. Matrix can define with `jobs.<job_id>.strategy.matrix`. Following example shows how to use matrix.
17881787

1789-
let's set secrets in settings.
1788+
- To control how job failures are handled, use `fail-fast: false` to continue other matrix jobs when one of matrix job fails.
1789+
- Matrix runs jobs in parallel by default. However you can set parallelism with `max-parallel` to limit number of parallel jobs.
1790+
- Matrix can define multiple axis like OS and version. Following example will run 6 jobs in parallel (3 versions x 2 OS).
1791+
1792+
```yaml
1793+
# .github/workflows/matrix.yaml
1794+
1795+
name: matrix
1796+
on:
1797+
workflow_dispatch:
1798+
push:
1799+
branches: ["main"]
1800+
pull_request:
1801+
branches: ["main"]
1802+
1803+
jobs:
1804+
parallel:
1805+
strategy:
1806+
# If set true, then if one matrix job fails, cancel others
1807+
fail-fast: false # default is true.
1808+
matrix:
1809+
version: [10, 12, 14]
1810+
runs-on: [ubuntu-24.04, ubuntu-latest]
1811+
permissions:
1812+
contents: read
1813+
runs-on: ${{ matrix.runs-on }}
1814+
timeout-minutes: 3
1815+
steps:
1816+
- name: Show runner info
1817+
run: |
1818+
echo "runner.os: ${{ runner.os }}"
1819+
echo "matrix.runs-on: ${{ matrix.runs-on }}"
1820+
echo "matrix.version: ${{ matrix.version }}"
1821+
1822+
serial:
1823+
strategy:
1824+
# run matrix jobs one by one = serial execution
1825+
max-parallel: 1
1826+
matrix:
1827+
version: [10, 12, 14]
1828+
runs-on: [ubuntu-24.04, ubuntu-latest]
1829+
permissions:
1830+
contents: read
1831+
runs-on: ${{ matrix.runs-on }}
1832+
timeout-minutes: 3
1833+
steps:
1834+
- name: Show runner info
1835+
run: |
1836+
echo "runner.os: ${{ runner.os }}"
1837+
echo "matrix.runs-on: ${{ matrix.runs-on }}"
1838+
1839+
```
1840+
1841+
**Secret dereference in matrix**
1842+
1843+
You cannot reference `secret` context inside `strategy.matrix` section, so pass secret key in matrix then dereference secret with `secrets[matrix.SECRET_KEY]`.
1844+
1845+
Let's set secrets in settings, then run following workflow.
17901846

17911847
![image](https://user-images.githubusercontent.com/3856350/79934065-99de6c00-848c-11ea-8995-bfe948e6c0fb.png)
17921848

@@ -1831,10 +1887,9 @@ jobs:
18311887
18321888
```
18331889

1834-
## Strategy matrix and environment variables
1890+
**Matrix reference in env**
18351891

1836-
you can refer matrix in job's `env:` section before steps.
1837-
However you cannot use expression, you must evaluate in step.
1892+
You can refer matrix in job's `env:` section before steps.
18381893

18391894
```yaml
18401895
# .github/workflows/matrix-envvar.yaml
@@ -1858,9 +1913,7 @@ jobs:
18581913
timeout-minutes: 3
18591914
env:
18601915
ORG: ${{ matrix.org }}
1861-
# you can not use expression. do it on step.
1862-
# output on step is -> ci-`date '+%Y%m%d-%H%M%S'`+${GITHUB_SHA:0:6}
1863-
# GIT_TAG: "ci-`date '+%Y%m%d-%H%M%S'`+${GITHUB_SHA:0:6}"
1916+
# you can not use expression inside env:. do it on step.
18641917
steps:
18651918
- run: echo "${ORG}"
18661919
- run: echo "${NEW_ORG}"
@@ -1869,6 +1922,42 @@ jobs:
18691922
18701923
```
18711924

1925+
**Matrix includes/excludes**
1926+
1927+
Ise `include` to expand existing matrix, and use `exclude` to remove matrix combinations. Both are optional, and you can directly specify `include` without specifying base matrix.
1928+
1929+
Following example shows `include` to define 3 matrix items, then `exclude` to remove one item from matrix. Result is 2 matrix jobs `apples` and `carrots`.
1930+
1931+
```yaml
1932+
# .github/workflows/matrix-include-exclude.yaml
1933+
1934+
name: matrix include exclude
1935+
on:
1936+
workflow_dispatch:
1937+
push:
1938+
branches: ["main"]
1939+
pull_request:
1940+
branches: ["main"]
1941+
1942+
jobs:
1943+
echo:
1944+
strategy:
1945+
matrix:
1946+
include:
1947+
- fruit: apples
1948+
- fruit: bananas
1949+
- fruit: carrots
1950+
exclude:
1951+
- fruit: bananas
1952+
permissions:
1953+
contents: read
1954+
runs-on: ubuntu-24.04
1955+
timeout-minutes: 3
1956+
steps:
1957+
- run: echo "${matrix.fruit}"
1958+
1959+
```
1960+
18721961
## Timeout settings
18731962

18741963
You can set timeout for both `job` and `steps`.
@@ -3169,6 +3258,39 @@ Service container is used to run container alongside your job. Typical usecase i
31693258

31703259
```yaml
31713260
# .github/workflows/container-service.yaml
3261+
3262+
name: Container Service
3263+
on:
3264+
workflow_dispatch:
3265+
push:
3266+
branches: ["main"]
3267+
pull_request:
3268+
branches: ["main"]
3269+
3270+
jobs:
3271+
container:
3272+
permissions:
3273+
contents: read
3274+
runs-on: ubuntu-24.04
3275+
timeout-minutes: 10
3276+
services:
3277+
redis:
3278+
image: redis:8
3279+
ports:
3280+
- 6379:6379
3281+
steps:
3282+
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
3283+
with:
3284+
persist-credentials: false
3285+
- uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0
3286+
with:
3287+
go-version: "1.25"
3288+
- name: Show Go version
3289+
run: go version
3290+
- name: Run Go program
3291+
run: go run main.go
3292+
working-directory: ./src/go-db
3293+
31723294
```
31733295

31743296
## Dispatch other repo workflow

0 commit comments

Comments
 (0)