How Pipeline Generation Works

With the CI/CD Automation for Simulink Check support package, you can define a process for your team and set up your CI system to run the tasks in that process as a pipeline in CI. A pipeline is a collection of automated procedures and tools that execute in a specific order to enable a streamlined software delivery process. CI systems allow you to define and configure a pipeline by using a pipeline file.

Typically, when you configure a CI pipeline, you need to manually create and update pipeline configuration files as you add, remove, and change the artifacts in your project. However, the example pipeline configuration files use a pipeline generator function, padv.pipeline.generatePipeline, that can generate the updated pipeline configuration files for you. After you do the initial setup for the pipeline generator, you do not need to manually update your pipeline configuration files. When you trigger your pipeline, the pipeline generator uses the digital thread to analyze the files in your project and uses your process model to generate pipeline configuration files for you.

Summary of Support

When you use the support package to integrate a model-based design (MBD) project into CI, there are three main approaches to creating and maintaining your pipeline configuration files:

• Manual Authoring — Each time you need to create or update your pipeline, you manually write, update, and check-in a pipeline configuration file that uses the runprocess function to run tasks. This approach allows you the most flexibility and ability to customize your pipeline, but requires that you regularly maintain the pipeline configuration file.

• Manual Generation — Each time you commit changes, you manually generate a pipeline configuration file using the padv.pipeline.generatePipeline function in your local MATLAB^® installation and then manually check the pipeline configuration file into your CI system. With this approach, you do not need to manually write the pipeline configuration file, but you do need to manually regenerate the pipeline for each submission.

• Automatic Generation — You perform a one-time setup of a parent pipeline configuration file that automatically calls the padv.pipeline.generatePipeline function and automatically generates an up-to-date, child pipeline configuration file that runs your process in CI. With this approach, you do not have to manually write or generate pipeline configuration files, but setting up a branching workflow can be complex.

The following table lists which approaches the support package supports on each CI platform.

Approaches \ Platforms	GitHub®	GitLab®	Jenkins®	Other MATLAB-Supported CI Platforms
Manual Authoring	✔	✔	✔	✔
Manual Generation	✔ (recommended)	✔	✔
Automatic Generation		✔ (recommended)	✔ (recommended)

For CI platforms, you typically define your CI pipeline by using a pipeline configuration file. For example, a YAML file on platforms like GitHub and GitLab or a Jenkinsfile on Jenkins.

Typically, when you configure a CI pipeline, you need to manually create and update your pipeline configuration files as you add, remove, and change the artifacts in your project. However, the support package has a pipeline generator function padv.pipeline.generatePipeline that you can use to generate the pipeline configuration files for GitHub, GitLab, and Jenkins.

For example, on a CI platform like GitLab, the pipeline generator can automatically generate the pipeline configuration files that you would need to create a pipeline that runs each job in your process, generate a report, and collect the artifacts from the pipeline.

Generated Pipelines

After you perform the initial setup and trigger your pipeline, the pipeline generator generates a parent pipeline and a child pipeline.

The parent pipeline contains two stages:

• Simulink Pipeline Generation — This stage analyzes your project and process model to automatically generate the pipeline configuration files to run your process in CI. If you want to view the generated pipeline configuration files, the pipeline generator stores the files under the derived > pipeline folder in the project.

• Simulink Pipeline Execution — This stage creates and executes a child pipeline that runs the tasks in your process, generates a build report, and collects the job artifacts.

By default, the child pipeline contains:

• One stage for each task in your process model.

• One stage that generates a build report, ProcessAdvisorReport.pdf.

• One stage that collects the job artifacts and compresses the artifacts into a zip file, padv_artifacts.zip.

Optional Pipeline Customization

You can run the pipeline generator using the default options or you can edit the example pipeline configuration file to customize how the pipeline generator creates and executes pipelines in CI.

The call to the pipeline generator function (padv.pipeline.generatePipeline) is in the example pipeline configuration file. The function padv.pipeline.generatePipeline requires you to specify a CI options object as an input.

The CI options object allows you to specify several properties of the generated CI pipeline, including:

• the pipeline architecture

• whether the pipeline generates a build report

• if and when the pipeline collects artifacts from the build

Pipeline Architecture

The pipeline architecture defines the number of stages and the grouping of tasks in the child pipeline. You can specify the pipeline architecture by using a padv.pipeline.Architecture object.

By default, the example pipeline configuration files specify the pipeline architecture as SerialStagesGroupPerTask, which creates one stage for each task in the process model. For example, one stage for TaskA and one stage for TaskB.

The available pipeline architectures are:

• SingleStage — A single stage, Runprocess, that runs all the tasks in the process.

• SerialStages — One stage for each task iteration in the process.

• SerialStagesGroupPerTask — One stage for each task in the process.

• IndependentModelPipelines — Parallel, downstream pipelines for each model. Each pipeline independently runs the tasks associated with the model.

Build Report

By default, the pipeline generator creates a stage, Generate_PADV_Report, that generates a build report for your pipeline. The build report is a PDF file ProcessAdvisorReport.pdf.

If you do not want to generate a report, you can specify the GenerateReport argument as false. For example, in a GitLab pipeline configuration file:

padv.pipeline.GitLabOptions(GenerateReport = false)

Build Artifacts

By default, the pipeline generator creates a stage, Collect_Artifacts, that collects and compresses the build artifacts from your pipeline. The ZIP file attached to the Collect_Artifacts stage is called padv_artifacts.zip. You can download these artifacts to locally reproduce issues seen in CI. For more information, see Locally Reproduce Issues Found in CI.

You can specify if and when you want the pipeline to collect artifacts by specifying the argument EnableArtifactCollection:

• "never", 0, or false — Never collect artifacts

• "on_success" — Only collect artifacts when the pipeline succeeds

• "on_failure" — Only collect artifacts when the pipeline fails

• "always", 1, or true — Always collect artifacts

For example, in a GitLab pipeline configuration file:

padv.pipeline.GitLabOptions(EnableArtifactCollection="on_failure")