The Setup MATLAB action enables you to set up MATLAB® and other MathWorks® products on a GitHub®-hosted (Linux®, Windows®, or macOS) runner or self-hosted UNIX® (Linux or macOS) runner. When you specify this action as part of your workflow, the action sets up your preferred MATLAB release (R2021a or later) on the runner. If you do not specify a release, the action sets up the latest release of MATLAB. As part of the setup process, the action prepends MATLAB to the PATH system environment variable.

Note: For GitHub-hosted runners, the Setup MATLAB action automatically includes the dependencies required to run MATLAB and other MathWorks products. However, if you are using a self-hosted runner, you must ensure that the required dependencies are available on your runner. For details, see Required Software on Self-Hosted Runners.

Once you set up MATLAB on a runner, you can build and test your MATLAB project as part of your workflow. To execute code on the runner, include the Run MATLAB Build, Run MATLAB Tests, or Run MATLAB Command action in your workflow.

Using the latest release of MATLAB on a GitHub-hosted runner, run the default tasks in a build file named buildfile.m in the root of your repository as well as all the tasks on which they depend. To set up the latest release of MATLAB on the runner, specify the Setup MATLAB action in your workflow. To run the tasks, specify the Run MATLAB Build action.

name: Run Default Tasks in Build File
on: [push]
jobs:
    my-job:
        name: Run MATLAB Build
        runs-on: ubuntu-latest
        steps:
            - name: Check out repository
              uses: actions/checkout@v7
            - name: Set up MATLAB
              uses: matlab-actions/setup-matlab@v3
            - name: Run build
              uses: matlab-actions/run-build@v3

Run your MATLAB and Simulink® tests in parallel (requires Parallel Computing Toolbox™) using the latest release of the required products on a GitHub-hosted runner. To set up the latest release of MATLAB, Simulink, Simulink Test, and Parallel Computing Toolbox on the runner, specify the Setup MATLAB action with its products input in your workflow. To run the tests in parallel, specify the Run MATLAB Tests action with its use-parallel input specified as true.

name: Run Tests in Parallel
on: [push]
jobs:
  my-job:
    name: Run MATLAB and Simulink Tests
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v7
      - name: Set up products
        uses: matlab-actions/setup-matlab@v3
        with:
          products: >
            Simulink
            Simulink_Test
            Parallel_Computing_Toolbox
      - name: Run tests
        uses: matlab-actions/run-tests@v3
        with:
          use-parallel: true

Using the latest release of MATLAB on a GitHub-hosted runner, run a script named myscript.m in the root of your repository. To set up the latest release of MATLAB on the runner, specify the Setup MATLAB action in your workflow. To run the script, specify the Run MATLAB Command action.

name: Run MATLAB Script
on: [push]
jobs:
    my-job:
        name: Run MATLAB Script
        runs-on: ubuntu-latest
        steps:
            - name: Check out repository
              uses: actions/checkout@v7
            - name: Set up MATLAB
              uses: matlab-actions/setup-matlab@v3
            - name: Run script
              uses: matlab-actions/run-command@v3
              with:
                  command: myscript

When you define a workflow using the Setup MATLAB action, you need a MATLAB batch licensing token if your project is private or if your workflow uses transformation products, such as MATLAB Coder™ and MATLAB Compiler™. Batch licensing tokens are strings that enable MATLAB to start in noninteractive environments. You can request a token by submitting the MATLAB Batch Licensing Pilot form.

To use a MATLAB batch licensing token:

1. Set the token as a secret. For more information about secrets, see Using secrets in GitHub Actions.
2. Map the secret to an environment variable named MLM_LICENSE_TOKEN in your workflow.

For example, define a workflow that runs the tests in your private project by using the latest release of MATLAB on a self-hosted UNIX runner:

• To set up the latest release of MATLAB on the self-hosted UNIX runner, specify the Setup MATLAB action in your workflow. (The runner must include all the dependencies required to run MATLAB.)
• To run the tests, specify the Run MATLAB Tests action. License MATLAB to run the tests by mapping a secret to the MLM_LICENSE_TOKEN environment variable in your workflow. In this example, MyToken is the name of the secret that holds the batch licensing token.

name: Use MATLAB Batch Licensing Token
on: [push]
env:
  MLM_LICENSE_TOKEN: ${{ secrets.MyToken }}
jobs:
  my-job:
    name: Run MATLAB Tests in Private Project
    runs-on: self-hosted
    steps:
      - name: Check out repository
        uses: actions/checkout@v7
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v3
      - name: Run tests
        uses: matlab-actions/run-tests@v3

The Setup MATLAB action supports the Linux, Windows, and macOS platforms. Define a matrix of job configurations to run a build using the MATLAB build tool on all the supported platforms. This workflow runs three jobs, one for each value in the variable os. For more information about matrices, see Using a matrix for your jobs.

name: Build Across Multiple Platforms
on: [push]
jobs:
  my-job:
    name: Run MATLAB Build
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v7
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v3
      - name: Run build
        uses: matlab-actions/run-build@v3
        with:
          tasks: test

When you define your workflow in the .github/workflows directory of your repository, specify the Setup MATLAB action as matlab-actions/setup-matlab@v3. The action accepts optional inputs.

Setting up MATLAB and other MathWorks products on a self-hosted UNIX runner requires certain dependencies to be installed on the runner. You can install these dependencies by using the install-system-dependencies action input.

Tip: If you are using a container on your self-hosted runner, you can satisfy the required dependencies by using the MATLAB Dependencies container image on Docker® Hub in your workflow.

If you are using a Linux runner, the following software must be installed on the runner:

• Third-party packages required to run the mpm command — To view the list of mpm dependencies, refer to the Linux section of Get MATLAB Package Manager.
• All MATLAB dependencies — To view the list of MATLAB dependencies, go to the MATLAB Dependencies repository on GitHub. Then, open the <release>/<system>/base-dependencies.txt file for your MATLAB release and your runner's operating system.

If you are using a macOS runner with an Apple silicon processor, Java® Runtime Environment (JRE™) must be installed on the runner. For information about this requirement and to get a compatible JRE version, see MATLAB on Apple Silicon Macs.

Product licensing for your workflow depends on your project visibility:

• Public project — The Run MATLAB Build, Run MATLAB Tests, and Run MATLAB Command actions automatically license all products for you, except for transformation products, such as MATLAB Coder and MATLAB Compiler.
• Private project — The actions do not automatically license any products for you.

To license products that are not automatically licensed, you can request a MATLAB batch licensing token by submitting the MATLAB Batch Licensing Pilot form. Batch licensing tokens are strings that enable MATLAB to start in noninteractive environments.

To use a MATLAB batch licensing token, first set it as a secret. Then, map the secret to an environment variable named MLM_LICENSE_TOKEN in your workflow. For an example, see Use MATLAB Batch Licensing Token.

• The Setup MATLAB action automatically includes the MATLAB batch licensing executable (matlab-batch). To use a MATLAB batch licensing token in a workflow that does not use this action, you must first download the executable and add it to the system path.
• Public project and MATLAB batch licensing do not support external language interfaces, including MATLAB Engine APIs for Python®, Java, .NET, COM, C, C++, and Fortran. To use external language interfaces in your workflow, use a self-hosted runner that has a version of MATLAB licensed without a batch token.
• When you use the Setup MATLAB action, you execute third-party code that is licensed under separate terms.

• Action for Running MATLAB Builds
• Action for Running MATLAB Tests
• Action for Running MATLAB Commands
• Continuous Integration with MATLAB and Simulink

If you encounter a product licensing issue, consider requesting a MATLAB batch licensing token to use in your workflow. For more information, see Use MATLAB Batch Licensing Token.

If you have an enhancement request or other feedback about this action, create an issue on the Issues page.

For support, contact MathWorks Technical Support.