Action for Running MATLAB Builds

Starting in R2022b, the MATLAB® build tool provides a standard programming interface to create and run tasks in a uniform and efficient way. For example, you can create tasks that identify code issues, run tests, and package a toolbox in a single build file in your project root folder, and then invoke the build tool to run these tasks. For more information, see Overview of MATLAB Build Tool.

The Run MATLAB Build action enables you to invoke the MATLAB build tool on a self-hosted or GitHub®-hosted runner:

• To use a self-hosted runner, you must set up a computer with MATLAB as your self-hosted runner and register the runner with GitHub Actions. The runner uses the topmost MATLAB release on the system path to execute your workflow.
• To use a GitHub-hosted runner, you must include the Setup MATLAB action in your workflow to set up your preferred MATLAB release (R2021a or later) on the runner.

Examples

Use the Run MATLAB Build action to run a build using the MATLAB build tool. You can use this action to run the tasks in your build file. (By default, the action looks for a build file named buildfile.m in the root of your repository.) To use the Run MATLAB Build action, you need MATLAB R2022b or a later release.

Run Default Tasks in Build File

On a self-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 run the tasks, specify the Run MATLAB Build action in your workflow.

name: Run Default Tasks in Build File
on: [push]
jobs:
  my-job:
    name: Run MATLAB Build
    runs-on: self-hosted
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Run build
        uses: matlab-actions/run-build@v2

Run Specified Task in Build File

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

name: Run Specified Task 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
        with:
          tasks: mytask

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 a MATLAB build 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 MATLAB build, specify the Run MATLAB Build 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 Build 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 build
        uses: matlab-actions/run-build@v2

Run MATLAB Build

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

Input	Description
tasks	(Optional) MATLAB build tasks to run, specified as a list of task names separated by spaces. If a task accepts arguments, enclose them in parentheses. If you do not specify tasks, the action runs the default tasks in your build file as well as all the tasks on which they depend. By default, the action looks for a build file named buildfile.m in the root of your repository. MATLAB exits with exit code 0 if the tasks run without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the action to fail. Example: tasks: test Example: tasks: compile test Example: tasks: check test("myFolder",OutputDetail="concise") archive("source.zip")
build-options	(Optional) MATLAB build options, specified as a list of options separated by spaces. The action supports the same options that you can pass to the buildtool command. Example: build-options: -continueOnFailure Example: build-options: -continueOnFailure -skip test
startup-options	(Optional) MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see Commonly Used Startup Options. Using this input to specify the -batch or -r option is not supported. Example: startup-options: -nojvm Example: startup-options: -nojvm -logfile output.log

Notes

• By default, when you use the Run MATLAB Build action, the root of your repository serves as the MATLAB startup folder. To run your MATLAB build using a different folder, specify the -sd startup option in the action.
• The Run MATLAB Build action uses the -batch option to invoke the buildtool command. Preferences do not persist across different MATLAB sessions launched with the -batch option. To run code that requires the same preferences, use a single action.
• When you use the Run MATLAB Build action, you execute third-party code that is licensed under separate terms.

See Also

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

Contact Us

If you have any questions or suggestions, contact MathWorks® at continuous-integration@mathworks.com.