Integrate Process into GitLab

This example uses:

CI/CD Automation for Simulink Check CI/CD Automation for Simulink Check

You can define a process for your team and set up your continuous integration (CI) system to automatically run the tasks in that process as a pipeline by using the CI/CD Automation for Simulink Check support package. The support package includes a GitLab^® template that defines CI jobs for each task in your process. You can reconfigure the template file to separate your tasks into different jobs 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 how to:

Set up a GitLab project and CI agent.
Connect a MATLAB^® project to GitLab.
Perform a one-time setup of a GitLab template 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

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 the GitLab documentation for Create a project.
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 the GitLab documentation for Install GitLab Runner.
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

To run CI jobs in parallel, you must either:

Have multiple runners available.
Configure your runner to run multiple jobs concurrently by specifying the concurrent setting. See the GitLab documentation for Advanced configuration.

Connect MATLAB Project to GitLab

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 an example process model.
```
processAdvisorExampleStart
```
The process model, processmodel.m, is at the root of the project and defines a process with common model-based design tasks. You can use the Process Advisor app to run the tasks in the process on your local machine. You can copy the default process model template into a project by entering createprocess(Template = "default") 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.
In MATLAB, 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 Use Source Control with Projects.

Configure Template to Use GitLab Runner

In 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 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.

The template file can then generate a GitLab pipeline with stages for each task in your process the next time that you push your changes to your remote repository. Optionally, you can further customize the template file to change how the pipeline generator organizes and executes the pipeline. You can dry run your tasks, separate your tasks into different jobs, and specify other options by using the padv.pipeline.GitLabOptions object in the template.

Make Optional Customizations

Optionally, you can reconfigure the template file to customize how the pipeline generator organizes and executes the pipeline. To customize the pipeline generator options, 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.
Separate tasks into different jobs.

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.SerialStagesGroupPerTask,
            RunprocessCommandOptions = rpo,
            Tags = 'padv_demo_ci',
            GeneratedYMLFileName = 'simulink_pipeline.yml', 
            GeneratedPipelineDirectory = fullfile('derived','pipeline')));
            "

This example code creates a padv.pipeline.RunProcessOptions object, rpo, that customizes the behavior of the runprocess function in CI. This code specifies the runprocess arguments DryRun and DryRunLicenseCheckout as true, updates the padv.pipeline.GitLabOptions object to use the PipelineArchitecture SerialStagesGroupPerTask, and uses 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 the GitLab documentation for CI/CD YAML syntax reference.

Generate Pipeline in GitLab

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 .gitlab-ci.yml as the CI/CD configuration file to automatically create pipelines when triggered.

Each time you submit changes to this remote repository, GitLab 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.
- The Generate_PADV_Report job, which generates a Process Advisor build report.
- The Collect_Artifacts job, which 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.