# How to build a CI matrix for an SDK across six languages

> Test TypeScript, Python, Go, PHP, Ruby and Lua SDKs on two or three runtimes each in one GitHub Actions matrix with one required status.

Source: https://voxgig.com/howto/sdk-ci-matrix-across-six-languages

- Audience: platform-team
- Level: intermediate
- Languages: typescript, python, go, php, ruby, lua
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

Write the GitHub Actions matrix as include entries, one per language and runtime version, set fail-fast to false, install each toolchain with its own setup action, and cache each language on its manifest. Add one job that needs the matrix, runs if: always(), and fails unless every cell succeeded. Count the jobs before you push, then break one language on purpose and confirm only its cells go red.

---
## You will need

A repository with each SDK in its own directory and a `make test` target in each, which is the
layout sdkgen generates, and GitHub Actions or GitLab CI. The sample's scripts need Node 22 or
later and run offline. The workflows were checked by those scripts and not run on either service.
The shell lines of the Composer cache step ran locally, against Composer 2.8.12.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [GitHub Actions matrix](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax) | One repository holds every SDK, and the code is on GitHub | One workflow with a setup step per language, each gated on `matrix.lang` | The SDKs live in separate repositories with separate owners |
| [GitLab CI parallel:matrix](https://docs.gitlab.com/ci/yaml/) | The repository is on GitLab, with an image per runtime | One job per language, and setup scripts inside images you trust | You need setup actions rather than container images |
| [openapi-typescript and openapi-fetch](https://openapi-ts.dev/cli) | TypeScript is the only SDK, generated as types | Covers one language, so the other five cells need generators of their own | Several languages must come from one tool |
| [sdkgen generated CI](https://github.com/voxgig/sdkgen) | The six SDKs come from one sdkgen model in one repository | A generated job per target, one runtime each, and no single status | You need two or three runtimes per language today |
| [Speakeasy target testing](https://www.speakeasy.com/docs/speakeasy-reference/workflow-file) | One repository per language, each released on its own cadence | A licensed test feature, and one status per repository, six for six languages | One status for all six languages, or no account |

Voxgig maintains sdkgen. It is one of five options in the table, with its own limits stated in its
row.

The single matrix keeps every language on one commit and one status, which suits a repository that
releases together. A repository per language, as Speakeasy recommends, lets each language move
on its own clock, at the price of six places to look. openapi-typescript is the cheapest cell to
run and covers one of the six.

## Read what sdkgen generates first

An sdkgen scaffold with the six targets writes `.github/workflows/ci.yml`, committed here as
`generated/sdkgen-ci.yml`. `check-workflow.mjs` reads a workflow and reports what a multi-language
pipeline needs from it.

```bash
node check-workflow.mjs generated/sdkgen-ci.yml
```

```text output
generated/sdkgen-ci.yml: 26 jobs
  versions: ts 1, py 1, go 1, php 1, rb 1, lua 1
  actions pinned to a commit: 50 of 50
  required status: none
  8 problem(s)
    26 job(s) run on a -latest label, which moves to a newer image without a change here
    ts: one runtime version only (24)
    py: one runtime version only (3.13)
    go: one runtime version only (1.24)
    php: one runtime version only (8.3)
    rb: one runtime version only (3.3)
    lua: one runtime version only (5.4)
    no job that needs every other job and fails unless all succeeded
```

Every action is pinned to a full commit SHA. The 26 jobs cover 26 targets, not only the six
here, and each skips its steps through `hashFiles` when its directory is absent, so 20 of them
start and check out for nothing. The rest of the list is the work.

## Write the matrix as include entries

One `include` entry per cell names the language and the runtime. With no other axis, GitHub runs
exactly the listed entries.

```yaml title="sdk-ci.yml"
    strategy:
      # One language failing must not cancel the others.
      fail-fast: false
      matrix:
        include:
          - { lang: ts, version: '22' }
          - { lang: ts, version: '24' }
          - { lang: py, version: '3.12' }
          - { lang: py, version: '3.13' }
          - { lang: py, version: '3.14' }
          - { lang: go, version: '1.26' }
          - { lang: go, version: '1.27' }
```

The Node, Python, Go and Ruby versions come from the cached tools in the
[Ubuntu 24.04 runner image](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md),
committed under `runner/`. The image carries PHP 8.3 and no Lua, so `setup-php` and
`gh-actions-lua` install the rest. Each language gets its setup action behind `if: matrix.lang`:
`actions/setup-node`, `setup-python`, `setup-go`, `shivammathur/setup-php`, `ruby/setup-ruby`,
and `leafo/gh-actions-lua` with `leafo/gh-actions-luarocks`. `fail-fast` defaults to `true`, and
then GitHub cancels every running cell when one fails.

The status job is what a branch rule requires:

```yaml title="sdk-ci.yml"
  sdk-ci:
    needs: test
    if: always()
    runs-on: ubuntu-24.04
    steps:
      - run: test "${{ needs.test.result }}" = success
```

`if: always()` makes it report after a failed cell, since a job whose `needs` failed is otherwise
skipped. The [needs context](https://docs.github.com/en/actions/reference/workflows-and-actions/contexts)
gives `success`, `failure`, `cancelled` or `skipped`.

```bash
node check-workflow.mjs sdk-ci.yml
```

```text output
sdk-ci.yml: 15 jobs
  versions: ts 2, py 3, go 2, php 3, rb 2, lua 2
  actions pinned to a commit: 11 of 11
  required status: sdk-ci
  0 problem(s)
```

## Count the jobs before you push

`matrix.mjs` expands a matrix by the include rules as GitHub's reference words them, and GitLab's
`parallel:matrix` by its own. Its counts are read from that documentation, since neither service
ran these files. Two mistakes sit in `pitfall/`: every axis crossed, and an `os` axis
added to the include list.

```bash
node matrix.mjs sdk-ci.yml pitfall/crossed.yml pitfall/os-axis.yml --gitlab gitlab-ci.yml
```

```text output
sdk-ci.yml: 14 jobs (GitHub allows 256 per matrix)
  ts   22 24
  py   3.12 3.13 3.14
  go   1.26 1.27
  php  8.3 8.4 8.5
  rb   3.4 4.0
  lua  5.3 5.4
pitfall/crossed.yml: 54 jobs (GitHub allows 256 per matrix)
  ts   9 jobs
  py   9 jobs
  go   9 jobs
  php  9 jobs
  rb   9 jobs
  lua  9 jobs
pitfall/os-axis.yml: 3 jobs (GitHub allows 256 per matrix)
  lua  5.4@ubuntu-24.04 5.4@macos-15 5.4@windows-2025
gitlab-ci.yml: 14 jobs (GitLab allows 200 per parallel:matrix)
  ts   22 24
  py   3.12 3.13 3.14
  go   1.26 1.27
  php  8.3 8.4 8.5
  rb   3.4 4.0
  lua  5.3 5.4
```

Crossing six languages, three version slots and three operating systems starts 54 jobs. The `os`
axis is worse. By the reference's rules, each include entry fits every original combination, so
each one overwrites the last, and three Lua jobs remain.[^1] Add an operating system as include entries, for the cells that
need it.

GitLab has no single matrix across jobs, so `gitlab-ci.yml` gives each language a job with its own
[`parallel:matrix`](https://docs.gitlab.com/ci/yaml/#parallelmatrix) and image:

```yaml title="gitlab-ci.yml"
py:
  extends: .sdk-test
  image: python:${PYTHON}
  variables: { SDK: py, PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip" }
  parallel:
    matrix:
      - PYTHON: ['3.12', '3.13', '3.14']
  cache: { key: "pip-$PYTHON", paths: [.pip/] }
```

A failed job already leaves the others running in GitLab, and the pipeline's status is the one
status.

## Break one language on purpose

The six generated suites ran here, one runtime each, through `run-cells.mjs`, which runs each
cell's command and keeps going after a failure, as `fail-fast: false` does. The second run put
`raise RuntimeError("broken on purpose")` at the top of the Python SDK's `__init__.py`.

```bash
node run-cells.mjs summary results/clean.json results/py-broken.json
```

```text output
results/clean.json: 6 cells ran, 0 failed
  pass  ts   node 22.23.5    exit 0   # tests 226; # pass 217; # fail 0
  pass  py   Python 3.13.18  exit 0   205 passed, 88 skipped
  pass  go   go1.24.7        exit 0   ok github.com/voxgig-sdk/bookshelf-sdk/go/test
  pass  php  PHP 8.3.6       exit 0   OK, but some tests were skipped!; Tests: 260, Assertions: 711, Skipped: 65.
  pass  rb   ruby 3.3.6      exit 0   262 runs, 147698 assertions, 0 failures, 0 errors, 70 skips
  pass  lua  Lua 5.4.6       exit 0   206 successes / 0 failures / 0 errors / 2 pending
results/py-broken.json: 6 cells ran, 1 failed
  pass  ts   node 22.23.5    exit 0   # tests 226; # pass 217; # fail 0
  FAIL  py   Python 3.13.18  exit 2   12 errors
  pass  go   go1.24.7        exit 0   ok github.com/voxgig-sdk/bookshelf-sdk/go/test
  pass  php  PHP 8.3.6       exit 0   OK, but some tests were skipped!; Tests: 260, Assertions: 711, Skipped: 65.
  pass  rb   ruby 3.3.6      exit 0   262 runs, 147698 assertions, 0 failures, 0 errors, 70 skips
  pass  lua  Lua 5.4.6       exit 0   206 successes / 0 failures / 0 errors / 2 pending
```

The break reached Python alone, because each SDK carries its own runtime code. On GitHub, push the
same break on a branch and expect the three Python cells and `sdk-ci` to go red while the other
eleven finish green. Revert it before merging.

## Test the same SDKs with Speakeasy or openapi-typescript

Speakeasy was not run; it needs an account. Its unit is a target, one per SDK. Its
[monorepo guide](https://www.speakeasy.com/docs/sdks/guides/creating-a-monorepo) recommends a
single SDK per GitHub repository for most uses, and gives each SDK its own generate and release
workflows even in a monorepo. A target in `.speakeasy/workflow.yaml` takes `testing: enabled: true`, and its
[workflow file reference](https://www.speakeasy.com/docs/speakeasy-reference/workflow-file) says
that runs target-specific testing such as `go test` or `pytest` after generation, if test generation
is licensed. The reference names no setting for runtime versions, so each repository needs its own
matrix and reports its own status. That suits teams that release each language separately better than one
matrix does.

openapi-typescript generates types and `openapi-fetch` is the runtime, so it fills the TypeScript
cells alone. Add its `--check` flag to those cells: it fails when the committed types no longer
match the document, and writes nothing.

```bash
npx openapi-typescript api.json -o ts-types/schema.d.ts --check
```

```text output
✨ openapi-typescript 7.13.0
```

```bash
npx openapi-typescript api-changed.json -o ts-types/schema.d.ts --check
```

```text output
✨ openapi-typescript 7.13.0
 ✘  Generated types are not up-to-date!
```

The [openapi-fetch page](https://openapi-ts.dev/openapi-fetch/) lists Node 18.0.0 or later, so both
Node cells sit inside its support. Where TypeScript is the only SDK, this pair needs one runtime
setup instead of six.

## Check it worked

The tests hold the expander to GitHub's own worked example, the workflow to its job count and
its pins, and the recorded runs to a failure that stays in the Python cell. Two more run the
Composer cache step under `bash -e` against a stand-in for Composer, and refuse the old form of
that step.

```bash
node --test ci.test.mjs
```

```text output
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

## When it goes wrong

The Node cells fail at setup once `setup-node` is given `cache: npm`. That cache keys on a
lockfile, and sdkgen's generated TypeScript SDK ships no `package-lock.json`. Cache `~/.npm` with
`actions/cache` keyed on `ts/package.json`, as `sdk-ci.yml` does. The PHP target's `.gitignore`
drops `composer.lock` on purpose, so the Composer cache keys on `composer.json` too.

The Composer cache step reports success and writes an empty directory. `composer config
cache-files-dir` reads `./composer.json`, so at the repository root it fails. It was run
locally at a root that held only `php/composer.json`. There it reported that the file `cannot be
found in the current directory`, and exited 1. Wrapped as `echo "dir=$(...)"`, the same line
exited 0 and wrote `dir=`, because the line takes the status of `echo`. The cache step then gets an empty `path`.
`sdk-ci.yml` passes `--working-dir php`, as its install step does, and assigns the result before
writing it. GitHub runs a step with no `shell` key as `bash -e {0}`, by its
[workflow syntax reference](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsshell),
so a failed assignment stops the step. `check-workflow.mjs` refuses both shapes.

A cell's toolchain changes under it with no commit to blame. The runner image readme committed
under `runner/`, for image version 20261116.376.1, announces that the `ubuntu-latest` label will
use Ubuntu 26.04 in November 2026. Pin `ubuntu-24.04` and move deliberately.

The status check never reports. Without `if: always()`, the status job is skipped when a cell
fails, and a branch rule that requires it waits. Keep `always()` and test `needs.test.result`.

## When not to do this

Do not cross languages with operating systems. Six languages on three systems is a bill for cells
nobody reads; add an operating system per language where its users need one.

Do not keep sdkgen's generated workflow as your only CI if you promise more than one runtime per
language. It tests one version of each, so the second runtime has to come from a matrix you add.

Do not force one matrix on SDKs that release on their own schedules. A repository per language,
the shape Speakeasy's targets take, gives each language its own status, on its own release clock.

Do not list a runtime nobody will fix. A cell is a promise to users, so Ruby 4.0 or Lua 5.3 in
the matrix means somebody owns them when they go red.

## Related how-tos

- [Layer unit, integration, and live tests for an SDK](/howto/layer-unit-integration-and-live-sdk-tests)

- [Run an in-memory mock of your API inside SDK tests](/howto/run-an-in-memory-mock-inside-sdk-tests)

- [Push one CI template change to five hundred repositories](/howto/push-one-ci-change-to-many-repositories)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Seed a sandbox account for SDK integration tests](/howto/seed-a-sandbox-account-for-sdk-integration-tests)

## Last verified

Verified 2026-11-21 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen`
4.44.3, `@voxgig/apidef` 8.32.4, `openapi-typescript` 7.13.0, TypeScript 5.9.3 and `yaml`
2.9.1. Every output block is what the command preceding it printed. The six generated suites ran
in a Linux sandbox twice, before and after Python was broken. They ran on Node 22.23.5, Python 3.13.18,
Go 1.24.7, PHP 8.3.6, Ruby 3.3.6 and Lua 5.4.6, with `busted` and `dkjson` from Ubuntu's apt packages.
Their results are committed under `results/`, which the captured commands read without those
runtimes. The Composer cache step's lookup ran locally with Composer 2.8.12 on PHP 8.3.6, at a
root holding only `php/composer.json`, with and without `--working-dir php`. Neither
workflow was run on GitHub or GitLab. Speakeasy was not run, and how it tests a target is read from its
documentation.

[^1]: GitHub's [workflow syntax reference](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)
adds an include entry to each combination it can join without overwriting an original value, and
notes that added values can be overwritten. Its worked example, on the page about
[running job variations](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations),
uses fruit, animals, colors and shapes, and ends with `{fruit: banana, animal: cat}` as a
combination of its own. It does not join `{fruit: banana}`, which arrived by include and so was
never an original.