Skip to content

containerization.md

Latest commit

 

History

History
92 lines (67 loc) · 6.39 KB

containerization.md

File metadata and controls

92 lines (67 loc) · 6.39 KB
Raw

Run MATLAB in Containers

In continuous integration (CI) workflows, you can run MATLAB®, Simulink®, and other MathWorks® products inside a container for improved security, consistency, and performance. Containers give you full control over the environment in which MATLAB runs. You can create and customize your own containers for CI.

For information on how to create a custom container image for CI workflows using a Dockerfile, see Create a MATLAB Container Image for Non-Interactive Workflows.

Note

Several CI platform integrations for MATLAB provide APIs to install and license MATLAB automatically on build agents. For example, on GitHub® Actions, you can use the setup-matlab action to install MATLAB on a GitHub-hosted or self-hosted runner. If you need full control over your environment, create your own container instead of relying on these integrations.

Install Products

The Dockerfile for noninteractive workflows includes:

  • The latest MATLAB release (without additional toolboxes)
  • The latest matlab-batch executable

When creating your own container image, you can customize the Dockerfile to include additional products. For details, see Customize the Image.

License Products

To license MathWorks products in a containerized CI workflow, use a MATLAB batch licensing token. These tokens allow MATLAB to start in noninteractive environments. Request a token by submitting the MATLAB Batch Licensing Pilot form.

Note

Do not paste the token into the Dockerfile. Instead, store it as a secret in your CI environment and use that secret to set an environment variable named MLM_LICENSE_TOKEN. For an example, see Use MATLAB Batch Licensing Token.

Run MATLAB in Container

After building your custom container image, reference it in your CI pipeline configuration file. The syntax for the image reference depends on your CI platform. For examples using GitHub Actions and GitLab® CI/CD, see Examples.

Then, you can use the CI platform integrations for MATLAB provided by MathWorks to:

  • Run a build using the MATLAB build tool.
  • Run MATLAB and Simulink tests, and generate test and coverage artifacts.
  • Run MATLAB scripts, functions, and statements.

For more information about the available integrations, see Continuous Integration with MATLAB on CI Platforms. If MathWorks does not provide an integration for your CI platform, invoke the matlab-batch executable in the container instead.

Examples

The following examples show how to define a CI pipeline to run the "test" task in a container. The examples have these assumptions:

  • You have a MATLAB batch licensing token stored as a secret in GitHub Actions or GitLab CI/CD.
  • Your repository contains a build file named buildfile.m with a "test" task for running MATLAB tests.
  • Your organization provides a custom container image named my-org/custom-matlab-image:r2025b.

GitHub Actions

To run a MATLAB build in GitHub Actions, use the run-build action. To use your custom container image and batch licensing token, use the container, image, and env keywords in the workflow definition.

For example, in your repository, create a YAML file in the .github/workflows directory to run a container from your custom image on a GitHub-hosted runner. Then, use the container to run the "test" task with the run-build action. In this example, MyToken is the secret that holds the MATLAB batch licensing token.

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-build-job:
    runs-on: ubuntu-latest
    container:
      image: my-org/custom-matlab-image:r2025b
      env:
        MLM_LICENSE_TOKEN: ${{ secrets.MyToken }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v6
      - name: Run build
        uses: matlab-actions/run-build@v3
        with:
          tasks: test

For more information, see Running jobs in a container.

GitLab CI/CD

To run MATLAB code and Simulink models in GitLab CI/CD, use the build component. By default, jobs created from the build component run using the latest release of MATLAB in the MATLAB container on Docker® Hub. To use your custom image, specify it with the matlab_image input.

For example, using the build component, in a file named .gitlab-ci.yml in the root of your repository, define a pipeline to run the "test" task in your custom container.

include:
  - component: $CI_SERVER_FQDN/mathworks/components/matlab/build@~latest
    inputs:
      tasks: test
      matlab_image: my-org/custom-matlab-image:r2025b

In GitLab CI/CD, the token-to-environment variable mapping occurs in the web UI. For details, refer to the documentation of the build component.

See Also

Copyright 2026 The MathWorks, Inc.