Integrate Process into GitLab

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 automatically run the tasks in that process as a pipeline in CI. The support package provides a GitLab^® template that defines CI jobs for each task in your process. You can reconfigure the template file to run model tasks, like code generation, in parallel and customize other pipeline behaviors. The template file uses the pipeline generator to automatically generate pipelines for you, so that you do not need to manually update CI/CD configuration files when you make changes to your project or processes.

This example shows the workflow to:

Set up a GitLab project and CI agent.
Connect a MATLAB^® project to GitLab.
Perform a one-time setup of a template GitLab YAML file to work with your CI setup.
Push changes to source control and inspect the automatically generated pipeline.

This example shows the recommended way to use your process in GitLab. Alternatively, you can manually author a pipeline configuration file that opens your project and runs your process as part of your build. For more information, Approaches to Running Processes in CI.

Set Up GitLab Project and Runner

To set up the CI system, you need to set up a source-controlled remote repository where you store your project and a CI agent machine that can run your pipeline on that repository. For this example, you can use GitLab as both your remote repository and CI system, and then create a GitLab Runner to run your pipelines.

In GitLab, set up a remote repository by creating a new blank project. See https://docs.gitlab.com/ee/.
Install, register, and start a GitLab Runner on a machine. The GitLab Runner application allows a machine to act as a CI agent in GitLab. If you assign a tag to your Runner, make note of the tag name. See https://docs.gitlab.com/runner/install/index.html.
Install MATLAB, Simulink^®, Simulink Check™, the CI/CD Automation for Simulink Check support package, and any other products that your process requires on the machine that has your GitLab Runner. Make sure that your GitLab Runner machine can access and run MATLAB before you continue.

For information on licensing considerations, Docker^® containers, and virtual displays, see Tips for Setting Up CI Agents.

Note

If you plan on running CI jobs in parallel, check that you either:

Have multiple runners available. See https://docs.gitlab.com/ee/ci/yaml/#parallel.
Configure your runner to run multiple jobs concurrently by specifying the concurrent setting. See https://docs.gitlab.com/runner/configuration/advanced-configuration.html.

Connect MATLAB Project to GitLab

You need to connect your MATLAB project to your remote repository so that you can push your changes to the remote GitLab repository and allow GitLab to automate a CI pipeline for the project.

Open a project in MATLAB. For this example, open an example project that uses the process defined by the parallel process model template.
```
processAdvisorParallelExampleStart
```
The process model, processmodel.m, is at the root of the project and defines a process with common model-based design tasks that can run model tasks like code generation in parallel in CI. You can use the Process Advisor app to run the tasks in the process on your local machine. You can copy the parallel process model template into a project by entering createprocess(Template = 'parallel') at the command line. For information on how to customize a template process model for your development and verification workflow, see Customize Your Process Model.
On the Project tab, in the Source Control section, click Remote and specify the URL for the remote origin in GitLab where your repository is hosted. For example, https://gitlab.com/gitlab-org/gitlab.git.
The example project is already set up to use local Git™ source control. For information on how to use source control with your projects, see Add a Project to Source Control.

Configure Template to use GitLab Runner

For GitLab, you define your CI pipelines by using a CI/CD configuration file, typically named .gitlab-ci.yml, in your project root. The support package includes a GitLab template file that you can reconfigure one time and then use to automatically generate pipelines.

Copy the GitLab template into your project folder. The GitLab template file is generic and can work with any project. In MATLAB, change your current folder to your project root and enter:
```
GitLabTemplate = fullfile(...
matlabshared.supportpkg.getSupportPackageRoot,...
"toolbox","padv","samples",".gitlab-ci-pipeline-gen.yml");

copyfile(GitLabTemplate,".gitlab-ci.yml")
```
In the Project pane, add the template file, .gitlab-ci.yml, to your project. The template file contains a CI pipeline definition for GitLab.
Open and inspect the template file. The file uses GitLab CI/CD YAML syntax to define a parent pipeline that can generate and execute pipelines for you.
Reconfigure the template to work for your CI setup. In the template, find and replace instances of padv_demo_ci with the tag name of the GitLab Runner that you want to use.
For example, if your GitLab Runner has the tag name high_memory, you specify that tag in the tags section and in the pipeline generation options object padv.pipeline.GitLabOptions.

At this point, the template file is set up to generate a GitLab pipeline with stages for each task in your process the next time that you push your changes to your remote repository. But you can, optionally, further customize the template file to change how the pipeline generator organizes and executes the pipeline. You can dry-run your tasks, run model tasks in parallel, and specify other options by using the padv.pipeline.GitLabOptions object in the template. For more information, see Optional Customizations.

Generate Pipeline in GitLab

When you are done editing the template file, commit and push the MATLAB project to your GitLab repository by using the Commit and Push buttons in the Source Control section of the Project tab. By default, GitLab uses the .gitlab-ci.yml at the root of the project as the CI/CD configuration file for the repository to automatically create pipelines when triggered.

Each time that you submit changes to this remote repository, GitLab automatically generates and executes a custom pipeline for your project, process, and pipeline generation options. You do not need to update the .gitlab-ci.yml file when you make changes to your projects or process model. The pipeline generator automatically generates up-to-date pipelines by using the latest project and process model. You only need to update the .gitlab-ci.yml file if you want to change how the pipeline generator organizes and executes the pipeline.

In GitLab, your pipeline contains two upstream jobs:

SimulinkPipelineGeneration — Generates a child pipeline file.
SimulinkPipelineExecution — Executes the child pipeline file. By default, the child pipeline contains:
- Jobs for your process, organized by the PipelineArchitecture property specified in padv.pipeline.GitLabOptions.
- One job, Generate_PADV_Report, that generates a Process Advisor build report.
- One job, Collect_Artifacts, that collects build artifacts.

Diagram for an example generated CI pipeline. The parent pipeline contains two stages (Simulink Pipeline Generation and Simulink Pipeline Execution) and a child pipeline. The child pipeline contains stages that run the tasks in the process model, generate a report, and collect artifacts.

Optional Customizations

You can reconfigure the template file to customize how the pipeline generator organizes and executes the pipeline. To customize the pipeline generator options, you modify the property values of the padv.pipeline.GitLabOptions object in the template.

For example, suppose that you want to:

Dry-run tasks to quickly validate task inputs and generate representative outputs without performing the full task operation.
Perform license checkouts during the dry-runs to make sure that your GitLab Runner has access to the required products.
Set up model tasks to run in parallel.

To change how the template file generates the pipeline, you can modify the padv.pipeline.GitLabOptions in the script section.

    script:
    # Open the project and generate the pipeline using
    # appropriate options in project root
        - >
            matlab
            -nodesktop
            -logfile "$MATLAB_LOG_FILE"
            -batch "
            cp = openProject(pwd);
            rpo = padv.pipeline.RunProcessOptions;
            rpo.DryRun = true;
            rpo.DryRunLicenseCheckout = true;
            padv.pipeline.generatePipeline(
            padv.pipeline.GitLabOptions(
            PipelineArchitecture = padv.pipeline.Architecture.IndependentModelPipelines,
            RunprocessCommandOptions = rpo,
            Tags = 'padv_demo_ci',
            GeneratedYMLFileName = 'simulink_pipeline.yml', 
            GeneratedPipelineDirectory = fullfile('derived','pipeline')));
            "

This example code creates a padv.pipeline.RunProcessOptions object, rpo, for customizing the behavior of the runprocess function in CI. In this case, specifying the runprocess arguments DryRun and DryRunLicenseCheckout as true. The code updates the padv.pipeline.GitLabOptions object to use a parallel PipelineArchitecture, IndependentModelPipelines, and use the RunprocessCommandOptions specified by rpo. For more information, see How Pipeline Generation Works.

If you modify other parts of the template file, make sure that your changes use valid GitLab CI/CD YAML syntax. For more information, see https://docs.gitlab.com/ee/ci/yaml/index.html.