Build MATLAB code once on a licensed self-hosted Linux runner, then package native application bundles for Windows, Linux, and macOS with GitHub-hosted runners.
No MLM_LICENSE_TOKEN is used. MATLAB is not installed on the Windows or macOS jobs.
The official matlab-actions/setup-matlab route is convenient until a workflow is private or uses a transformation product such as MATLAB Compiler. Those cases require a MATLAB batch licensing token obtained through the Batch Licensing Pilot. Batch licensing also does not support external-language interfaces, for which MathWorks recommends a normally licensed self-hosted runner.
That makes a conventional three-OS MATLAB build matrix awkward:
- three operating systems need MATLAB setup;
- MATLAB Compiler licensing must work in ephemeral CI jobs;
- the batch token is not a normal license key and is not always available;
- each platform repeats an expensive compilation.
If you already have an activated Linux machine with MATLAB, MATLAB Compiler, and MATLAB Compiler SDK, there is a much simpler split.
flowchart LR
A[MATLAB source] --> B[Self-hosted Linux runner<br/>MATLAB R2026a + Compiler SDK]
B --> C[Portable CTF archive]
C --> W[Windows runner<br/>JDK + jpackage]
C --> L[Linux runner<br/>JDK + jpackage]
C --> M[macOS runner<br/>JDK + jpackage]
W --> RW[Windows ZIP]
L --> RL[Linux tar.gz]
M --> RM[macOS app ZIP]
MATLAB R2026a introduced the generic MATLAB Compiler SDK API for Java. It produces a platform-independent CTF archive for platform-independent MATLAB code. The remaining jobs only:
- compile a small Java launcher;
- bundle a Java 17 runtime with
jpackage; - add the same CTF archive;
- create a native application image and upload it to the release.
- one MATLAB compilation instead of three;
- no MATLAB installation on GitHub-hosted packaging runners;
- no batch licensing token or
MLM_LICENSE_TOKENsecret; - Windows x86-64, Linux x86-64, and native Apple silicon packages;
- a startup splash instead of an apparently frozen application;
- persistent launcher logs on every platform;
- native
.ico,.png, and.icnsapplication icons; - direct GitHub Release uploads without duplicating large release files in Actions artifact storage;
- one-day artifacts for manual test builds.
The generated application bundles include Java, but do not include MATLAB Runtime. End users must install the free MATLAB Runtime matching the MATLAB release used for compilation. An R2026a CTF requires R2026a Runtime; this is not a >= R2026a dependency.
The launcher detects a missing Runtime, explains which release is required, and opens the official download page.
On one Linux machine:
- 64-bit Linux supported by MATLAB R2026a;
- MATLAB R2026a;
- MATLAB Compiler;
- MATLAB Compiler SDK;
- a normal activated license that can run noninteractively;
- a GitHub self-hosted runner registered for the repository.
On GitHub-hosted runners, the workflow installs Temurin JDK 17. No MATLAB products are installed there.
- Click Use this template and create your repository.
- Register your activated Linux machine as a repository self-hosted runner.
- Confirm MATLAB is installed at
/usr/local/MATLAB/R2026a, or editMATLAB_ROOTin release.yml. - Run Actions → Build cross-platform MATLAB release → Run workflow.
- Download the three one-day test artifacts and test them with MATLAB Runtime R2026a.
- Publish a GitHub Release. The same workflow uploads the platform archives and
SHA256SUMS.txtdirectly to that release.
See self-hosted runner setup for the complete machine setup.
The sample builds a small uifigure application. Replace these pieces:
| File | Change |
|---|---|
matlab/launch_demo.m |
Start your MATLAB UI and return after the first window is visible. |
matlab/build_release.m |
Add application files and folders through AdditionalFiles. |
launcher/app.properties |
Set the display name, CTF filename, entry point, and Runtime release. |
.github/workflows/release.yml |
Set APP_NAME, CTF_NAME, paths, and runner labels. |
launcher/icons/app.svg |
Replace the source icon, then run scripts/generate-icons.sh. |
Read customizing the template before replacing the demo with an App Designer application.
Create and publish a release in the GitHub UI, or use the GitHub CLI:
gh release create v1.0.0 --generate-notes --title "v1.0.0"The release.published event starts the pipeline. A successful release contains:
MatlabCtfDemo-v1.0.0-windows-x86_64.zip
MatlabCtfDemo-v1.0.0-linux-x86_64.tar.gz
MatlabCtfDemo-v1.0.0-macos-arm64.zip
SHA256SUMS.txt
The template ad-hoc signs the macOS bundle so its internal signature is consistent. It is not notarized. Windows packages are also unsigned. Production distribution should add Apple Developer ID signing/notarization and Windows code signing.
Never run untrusted pull-request code on a self-hosted runner containing a MATLAB license. This workflow intentionally runs only through workflow_dispatch and release.published; it does not run for pull requests.
Template code is available under the MIT License. MATLAB, MATLAB Compiler, MATLAB Compiler SDK, and MATLAB Runtime are MathWorks products and are governed by their own licenses. This repository does not distribute MathWorks software.