Approaches to Running Processes in CI

With the support package CI/CD Automation for Simulink Check, you can define a process for your team and set up your CI system to automatically run that process when you push code changes to your repository, create a pull request, or perform other pipeline triggering events. By automatically running your process, you can help your team find and fix problems in the software and improve software quality. For more information on CI workflows and benefits, see Develop and Integrate Software with Continuous Integration.

Before You Integrate

Your process model file defines the pipeline of tasks that the runprocess function runs in CI. If you do not already have a process model, the support package includes process model templates that you can use to get started. For more information, see Automate and Run Tasks with Process Advisor.

Before you try to run your process as part of an automated pipeline of tasks in CI, you need to connect your CI platform, remote repository, and project.

Choose a CI platform to run MATLAB^®. MATLAB integrates with common CI platforms like GitHub^®, GitLab^®, Jenkins^®, and other CI platforms.
Create a remote repository for your project. Many platforms, like GitHub and GitLab, provide source-controlled remote repositories as part of their platform. For other CI platforms, like Jenkins, you need to host your remote repository on another platform. See the documentation for your chosen CI platform to identify how you want to set up your remote repository.
Set up a CI agent. Your CI agent machine is responsible for running MATLAB and communicating the results back to your chosen CI platform. Depending on the CI platform, you can set up the platform to run MATLAB on your own, self-hosted machine or in the cloud. Make sure that your CI agent can run MATLAB and that you install the support package and any other products required by your process. For more information, see Tips for Setting Up CI Agents.
Connect your project, remote repository, and CI platform. On the Project tab, in the Source Control section, click Remote and specify the URL for your remote repository. For more information, see Use Source Control with Projects.
Make sure that your process model file is available on the MATLAB path for your CI agent. As a best practice, keep your process model file in the project root folder and add the process model file to the project.

Depending on your CI platform, you have different options for how to configure and run your process in CI.

GitHub

Basic Integration

You can manually author a GitHub Actions workflow file that opens your project and runs your process as part of a workflow. In the file, you can define a sequence of steps that checks out your repository code, opens your project using the openProject function, and runs your process using the runprocess function. To access an example workflow file and project, enter processAdvisorGitHubExampleStart at the MATLAB command line.

Recommended Integration

For a more robust and customizable CI integration, you can generate GitHub Actions workflow file for your process by using the pipeline generator in the support package. When you use the generated files in the workflow that you define in the .github/workflows directory of your repository, your project can create a pipeline of tasks for your process in CI. You can create pipelines that separate your tasks into different jobs, run model tasks in parallel, and use other custom pipeline behaviors.

For more information, see Integrate Process into GitHub.

GitLab

Basic Integration

You can modify the MATLAB YAML template to run the openProject and runprocess functions as commands in GitLab. For more information, see Use MATLAB with GitLab CI/CD.

Recommended Integration

For a more robust and customizable CI integration, use the Process Advisor YAML template as your pipeline YAML file (.gitlab-ci.yml). After you add the template to your project and perform a one-time setup, your project can automatically create pipelines with different jobs for each task in your process in CI. You can reconfigure the template to create pipelines that run model tasks in parallel and use other custom pipeline behaviors. The template uses the pipeline generator to analyze your project and process model to automatically generate the necessary pipeline files for you, so that you do not need to manually update those files when you make changes to the tasks and artifacts in your project. Inside the script section of the template, you specify the pipeline generation options.

For more information, see Integrate Process into GitLab.

Jenkins

Basic Integration

You can install the MATLAB plugin on your Jenkins agent and use the Run MATLAB Command build step to open your project and run your process with the openProject and runprocess functions. For more information, see the plugin on Jenkins Plugins Index.

Recommended Integration

For a more robust and customizable CI integration, use the Process Advisor Jenkinsfile template. After you add the template to your project and perform a one-time setup, your project can automatically create pipelines with different jobs for each task in your process in CI. You can reconfigure the template to create pipelines that run model tasks in parallel and use other custom pipeline behaviors. The template uses the pipeline generator to analyze your project and process model and automatically generate the necessary pipeline files for you, so that you do not need to manually update those files when you make changes to the tasks and artifacts in your project. Inside the Pipeline Generation stage of the template, you specify the pipeline generation options.

For more information, see Integrate Process into Jenkins.

Other Platforms

For other platforms, you can use the matlab command with the -batch option in your CI system. You can use matlab -batch to run MATLAB code, including the openProject and runprocess functions, noninteractively. For example, matlab -batch "openProject(pwd);runprocess();" starts MATLAB noninteractively, opens the project in the current working directory, and runs each of the tasks in the pipeline defined by the available process model file (processmodel.p or processmodel.m). MATLAB terminates automatically with the exit code 0 if the specified code executes successfully without generating an error. Otherwise, MATLAB terminates with a nonzero exit code.

For more information, see Continuous Integration with MATLAB on CI Platforms.