Approaches to Running Processes in CI

This example uses:

CI Support Package for Simulink CI Support Package for Simulink

With the CI Support Package for Simulink, 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 must connect your CI platform, remote repository, and project.

Choose a CI platform to run MATLAB^®. MATLAB integrates with common CI platforms like Azure^® DevOps, 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 must 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 build agent. Your build agent 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 build 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 and Build and Use Docker Image to Run Processes.
Connect your project, remote repository, and CI platform by adding the remote URL to your local repository. For more information, see Share Git Repository to Remote.
Make sure that your process model file is available on the MATLAB path for your build 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.

Azure DevOps

Basic Integration

Install the MATLAB extension to your Azure DevOps organization. To run MATLAB in your pipeline, you can use the extension to manually author your pipeline in a file named azure-pipelines.yml in the root of your repository. In the file, you can open your project using the openProject function and run your process using the runprocess function. To access an example pipeline file and project, enter processAdvisorAzureExampleStart at the MATLAB command line. You can run your pipeline using a Microsoft^®-hosted or self-hosted agent. For more information, see the extension on Visual Studio Marketplace.

To enable incremental builds, make sure jobs can access task outputs and the digital thread file (derived/artifacts.dmr). The build system uses these files to determine if tasks are up-to-date.

Recommended Integration

For a more robust and customizable CI integration, you can generate Azure DevOps pipeline file for your process by using the pipeline generator in the support package. When you use the generated pipeline files, your project can create a pipeline of tasks for your process in CI. You can create pipelines that separate your tasks into different jobs and use other custom pipeline behaviors.

To enable incremental builds, the pipeline generator automatically handles the propagation of your task outputs and digital thread file (derived/artifacts.dmr).

For more information, see Process Integration and Artifact Management for Azure DevOps.

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.

To enable incremental builds, make sure jobs can access task outputs and the digital thread file (derived/artifacts.dmr). The build system uses these files to determine if tasks are up-to-date.

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 and use other custom pipeline behaviors. This approach supports managing pipeline artifacts with network storage, JFrog Artifactory, Amazon S3™, and Azure Blob.

To enable incremental builds, the pipeline generator automatically handles the propagation of your task outputs and digital thread file (derived/artifacts.dmr).

For more information, see Process Integration and Artifact Management for 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.

To enable incremental builds, make sure jobs can access task outputs and the digital thread file (derived/artifacts.dmr). The build system uses these files to determine if tasks are up-to-date.

Recommended Integration

For a more robust and customizable CI integration, use the Process Advisor template files .gitlab-ci.yml and generate_gitlab_pipeline.m. After you add the templates 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 templates to create pipelines that separate your tasks into different jobs and use other custom pipeline behaviors. The templates use the pipeline generator to analyze your project and process model and automatically generate 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. This approach supports managing pipeline artifacts with network storage, JFrog Artifactory, Amazon S3, and Azure Blob.

To enable incremental builds, the pipeline generator automatically handles the propagation of your task outputs and digital thread file (derived/artifacts.dmr).

For more information, see Process Integration and Artifact Management for 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.

To enable incremental builds, make sure jobs can access task outputs and the digital thread file (derived/artifacts.dmr). The build system uses these files to determine if tasks are up-to-date.

Recommended Integration

For a more robust and customizable CI integration, use the Process Advisor template files Jenkinsfile_pipeline_gen and generate_jenkins_pipeline.m. After you add the templates 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 templates to create pipelines that separate your tasks into different jobs and use other custom pipeline behaviors. The templates use 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. This approach supports managing pipeline artifacts with network storage, JFrog Artifactory, Amazon S3, and Azure Blob.

To enable incremental builds, the pipeline generator automatically handles the propagation of your task outputs and digital thread file (derived/artifacts.dmr).

For more information, see Process Integration and Artifact Management for 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.

To enable incremental builds, make sure jobs can access the:

task outputs
digital thread file (derived/artifacts.dmr)

The build system uses these files to determine if tasks are up-to-date.

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