Process Integration and Artifact Management for Azure DevOps

Since R2023b. Recommended over Integrate Process into Azure DevOps.

This example uses:

You can set up continuous integration (CI) for your model-based design projects in Azure® DevOps by using the CI Support Package for Simulink. The support package allows you to run pipelines of tasks in Azure DevOps and manage artifacts by using network storage, JFrog Artifactory, Amazon S3™, or Azure Blob storage.

This example shows how to:

  1. Set up an Azure repository and Azure DevOps agent for running processes.

  2. Define tasks for your project by using an example process model.

  3. Connect your MATLAB® project to a remote Azure DevOps repository for source control integration.

  4. Generate a CI pipeline file and supporting files that enable you to run an Azure DevOps pipeline for your specific process model and pipeline settings.

This example shows the recommended way to integrate your process into Azure DevOps by using pipeline generator version 2, which has enhanced file propagation and artifact management. For alternatives, see Approaches to Running Processes in CI.

Set Up Azure DevOps Project

To set up the CI system, you must set up a source-controlled remote repository where you store your project and a build agent that can run your pipeline on that repository. Typically, the build agent is a self-hosted build agent rather than a cloud-hosted build agent. For this example, you can use Azure DevOps for both your remote repository and CI system, and then create a self-hosted Azure DevOps agent to run your pipelines.

  1. Install the MATLAB extension to your Azure DevOps organization. For more information, see the extension on Visual Studio Marketplace.

  2. In Azure DevOps, create a Azure Repos repository. See the Azure DevOps documentation for Create a project in Azure DevOps .

  3. Create an Azure DevOps agent. See the Azure DevOps documentation for Azure Pipelines agents .

  4. Install the required products and tools on your build agent by using one of these approaches:

    • Option 1: Manually Install Products and Tools on Build Agent

      1. Install MATLAB, Simulink®, Simulink Check™, the CI Support Package for Simulink, and any other products that your process requires. For more information, see Tips for Setting Up CI Agents.

      2. Install Python® with the alias python3 available in your system path. The pipeline generator was developed with Python 3.11. Optionally, to add colors to CI job logs, install the Python library colorlog.

      3. By default, the pipeline generator assumes that you have a shared network storage location for artifacts. However, if you plan to use an external artifact management system instead, make sure to install the CLI tool for your chosen system:

    • Option 2: Use Prebuilt Docker® Image

      You can simplify and automate build agent setup by using a prebuilt Docker image as your build environment. You can create a Docker image for pipeline generation by following the steps in Build and Use Docker Image to Run Processes. The image includes the CI support package, Python, artifact management CLIs, and other CI tools for pipeline generation.

Before you continue, make sure MATLAB is available on the system PATH so the build agent can access MATLAB.

Connect MATLAB Project to Repository and Azure DevOps

Connect your MATLAB project to your remote repository so that you can push your changes to the remote Azure project and allow Azure DevOps to automate a CI pipeline for the project.

  1. For this example, create a copy of the Process Advisor example project for Azure DevOps.

    processAdvisorAzureExampleStart

    This example project contains:

    • A process model, processmodel.m, that defines a process with common model-based design tasks. For information on how to customize a template process model for your development and verification workflow, see Customize Your Process Model.

    • An example pipeline file, simulink_pipeline.yml. In this example, you generate a new, customized version of the simulink_pipeline.yml pipeline file that provides your Azure DevOps pipeline information about your specific project and process.

  2. 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. Typically a remote URL has the format https://dev.azure.com/organization/project/_git/repo.

Generate Pipeline File and Supporting Files

You generate the Azure DevOps pipeline file and its supporting files by using the pipeline generator in MATLAB.

  1. Configure the pipeline generator options by creating a padv.pipeline.AzureDevOpsOptions object and specifying the GeneratorVersion property as 2.

    op = padv.pipeline.AzureDevOpsOptions(GeneratorVersion=2);

  2. Configure the pipeline generator to use your Azure DevOps agent pool and support package installation by specifying the properties AgentPoolName and SupportPackageRoot. You can find the location of your support package root by using the function matlabshared.supportpkg.getSupportPackageRoot on your build agent.

    op.AgentPoolName = "MyPool";
op.SupportPackageRoot = "C:\\ProgramData\\MATLAB\\SupportPackages\\R2025a\\bin"

  3. Choose where to store your pipeline artifacts by setting the ArtifactServiceMode property. Each artifact storage approach has its own specific configuration requirements as shown in ArtifactServiceMode. Depending on which artifact storage approach you choose, you need to specify additional properties and credentials.

    Artifact Storage ApproachExample CodeRequired Credentials

    Network storage

    op.ArtifactServiceMode = "network";
op.NetworkStoragePath = "/artifactManagement/cacheStorage";

    None.

    JFrog Artifactory

    op.ArtifactServiceMode = "jfrog";
op.ArtifactoryUrl = "http://localhost:8082/artifactory";
op.ArtifactoryRepoName = "example-repo-local";

    Store the JFrog API token as a secret variable named ARTIFACTORY_API_TOKEN_SECRET in Azure DevOps.

    Amazon S3

    op.ArtifactServiceMode = "s3";
op.S3BucketName = "my-artifacts-bucket";
op.S3AwsAccessKeyID = "AKIAIOSFODNN7EXAMPLE";

    Store the Amazon S3 access key as a secret variable named S3_AWS_SECRET_ACCESS_KEY_SECRET in Azure DevOps.

    Azure Blob

    op.ArtifactServiceMode = "azure_blob";
op.AzContainerName = "mycontainer";

    Store the Azure storage account connection string as a secret variable named AZ_CONNECTION_STRING_SECRET in Azure DevOps.

  4. Optionally, if you want to runs tasks inside a containerized environment, such as a Docker container, uncomment and specify the properties RunnerType and ImageTag. For example:

    op.RunnerType = "container";
op.ImageTag = 'my-docker-image-name';
    Depending on your setup, you might need to make adjustments to the MatlabLaunchCmd, MatlabStartupOptions, AddBatchStartupOption properties. For example:
    % Docker image settings
op.MatlabLaunchCmd = "xvfb-run -a matlab -batch"; 
op.MatlabStartupOptions = "";
op.AddBatchStartupOption = false;

  5. Optionally, you can customize other pipeline generator behaviors by modifying the other properties of the padv.pipeline.AzureDevOpsOptions object. For example, by default, the pipeline generator runs the process in a single stage. To have a pipeline with a stage for each task iteration, you can specify:

    op.PipelineArchitecture = "SerialStages";

    Note

    If you decide to use the IndependentModelPipelines architecture to generate code and perform code analysis tasks in parallel, you must either switch to using the template parallel process model or update your existing process as shown in Considerations for Parallel Code Generation. These updates allow the tasks in your pipeline to properly handle shared utilities and code generated across parallel jobs.

  6. Generate the pipeline file and supporting files by calling the padv.pipeline.generatePipeline function on your padv.pipeline.AzureDevOpsOptions object.

    padv.pipeline.generatePipeline(op)
    The pipeline generator generates these files:

    • In the derived\pipeline directory:

      • ir_dag.json — Pipeline data file that stores information about the task iterations and pipeline options for your specific project and process.

      • simulink_pipeline.yml — Pipeline file that defines an Azure DevOps pipeline.

    • In the templates directory:

      • generic-job.yml — Pipeline template file.

Use Generated Files to Define Azure DevOps Pipeline

  1. Copy the generated pipeline file, simulink_pipeline.yml, and data file, ir_dag.json, from derived\pipeline to the root of your repository.

  2. Edit the simulink_pipeline.yml file to specify the paths to the generated files.

    For this example, replace "/path/to/ir_dag.json" and "/path/to/simulink_pipeline.yml" with "ir_dag.json" and "simulink_pipeline.yml" respectively.

    cp "ir_dag.json" "$(MW_PIPELINE_GEN_PATH)/" 
cp "simulink_pipeline.yml" "$(MW_PIPELINE_GEN_PATH)/"

  3. Add the generated files to source control, then commit and push your changes.

    By default, simulink_pipeline.yml expects generic-job.yml to be in a folder named templates in the repository root. If you want to place the generic-job.yml file elsewhere in your repository, set the TemplatePath property in your padv.pipeline.AzureDevOpsOptions object and regenerate the pipeline files.

  4. In Azure DevOps, configure your pipeline to use the existing simulink_pipeline.yml file from the repository root as your Azure Pipelines YAML file.

When you run or trigger your pipeline, Azure DevOps creates the pipeline using the pipeline file, simulink_pipeline.yml. You can see your process running by navigating to the Pipelines section of your Azure DevOps project.

See Also

|

Topics