Action for Setting Up MATLAB

The Setup MATLAB action enables you to set up MATLAB® and other MathWorks® products on a GitHub®-hosted runner. When you specify this action as part of your workflow, the action sets up your preferred MATLAB release (R2021a or later) on a Linux®, Windows®, or macOS 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.

Examples

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.

Run Default Tasks in Build File

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@v4
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v2
      - name: Run build
        uses: matlab-actions/run-build@v2

Run Tests in Parallel

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@v4
      - name: Set up products
        uses: matlab-actions/setup-matlab@v2
        with:
          products: >
            Simulink
            Simulink_Test
            Parallel_Computing_Toolbox
      - name: Run tests
        uses: matlab-actions/run-tests@v2
        with:
          use-parallel: true

Run MATLAB Script

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@v4
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v2
      - name: Run script
        uses: matlab-actions/run-command@v2
        with:
          command: myscript

Use MATLAB Batch Licensing Token

On a GitHub-hosted runner, you need a MATLAB batch licensing token if your project is private or if your workflow includes 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, use the latest release of MATLAB on a GitHub-hosted runner to run the tests in your private project. To set up the latest release of MATLAB on the runner, specify the Setup MATLAB action in your workflow. To run the tests, specify the Run MATLAB Tests action. 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: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v2
      - name: Run tests
        uses: matlab-actions/run-tests@v2

Build Across Multiple Platforms

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@v4
      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v2
      - name: Run build
        uses: matlab-actions/run-build@v2
        with:
          tasks: test

Set Up MATLAB

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

Input	Description
release	(Optional) MATLAB release to set up. You can specify R2021a or a later release. By default, the value of release is latest, which corresponds to the latest release of MATLAB. To set up the latest update of a release, specify only the release name, for example, R2023b. To set up a specific update release, specify the release name with an update number suffix, for example, R2023bU4. To set up a release without updates, specify the release name with an update 0 or general release suffix, for example, R2023bU0 or R2023bGR. Example: release: R2023b Example: release: latest Example: release: R2023bU4
products	(Optional) Products to set up in addition to MATLAB, specified as a list of product names separated by spaces. You can specify products to set up most MathWorks products and support packages. The action uses MATLAB Package Manager (mpm) to set up products. For a list of supported products, open the input file for your preferred release from the mpm-input-files folder on GitHub. Specify products using the format shown in the input file, excluding the #product. prefix. For example, to set up Deep Learning Toolbox™ in addition to MATLAB, specify products: Deep_Learning_Toolbox. For an example of how to use the products input, see Run Tests in Parallel. Example: products: Simulink Example: products: Simulink Deep_Learning_Toolbox
cache	(Optional) Option to enable caching with GitHub Actions, specified as false or true. By default, the value is false and the action does not store MATLAB and the specified products in a GitHub Actions cache for future use. For more information about caching with GitHub Actions, see Caching dependencies to speed up workflows. Example: cache: true

Licensing

Product licensing for your workflow depends on your project visibility as well as the type of products to set up:

• Public project — If your workflow does not include transformation products, such as MATLAB Coder and MATLAB Compiler, then the action automatically licenses any products that you set up. If your workflow includes transformation products, you can request a MATLAB batch licensing token by submitting the MATLAB Batch Licensing Pilot form.
• Private project — The action does not automatically license any products for you. You can request a batch licensing token by submitting the MATLAB Batch Licensing Pilot form.

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.

Notes

• 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.
• When you use the Setup MATLAB action, you execute third-party code that is licensed under separate terms.

See Also

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

Contact Us

If you have any questions or suggestions, contact MathWorks at [email protected].