padv.pipeline.GitLabOptions

Options for generating pipeline configuration file for GitLab

expand all in page

    Description

    Use the padv.pipeline.GitLabOptions object to represent the desired options for generating a GitLab® pipeline configuration file. To generate a GitLab pipeline configuration file, use padv.pipeline.GitLabOptions as an input argument to the padv.pipeline.generatePipeline function. For information on how to use the pipeline generator to integrate into a GitLab CI system, see Integrate Process into GitLab.

    Creation

    Syntax

    options = padv.pipeline.GitLabOptions
    options = padv.pipeline.GitLabOptions(PropertyName=Value)

    Description

    options = padv.pipeline.GitLabOptions returns configuration options for generating a GitLab pipeline configuration file.

    example

    options = padv.pipeline.GitLabOptions(PropertyName=Value) sets properties using one or more name-value arguments. For example, padv.pipeline.GitLabOptions(Tags="high_memory") creates an options object that specifies that a generated pipeline configuration file use high_memory as the GitLab CI/CD tag.

    Properties

    expand all

    GitLab CI/CD tags, specified as a string or string array. Use this property to specify the tags that appear next to the tags keyword in a generated GitLab pipeline configuration file.

    The GitLab CI/CD tags select a GitLab Runner for a job. The property Tags specifies which CI/CD tags appear next to the tags keyword in a generated pipeline configuration file.

    For more information, see the tags keyword in the GitLab CI/CD YAML syntax reference.

    Example: options = padv.pipeline.GitLabOptions(Tags="high_memory")

    Data Types: string

    When to collect build artifacts, specified as:

    • "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

    If the pipeline collects artifacts, the child pipeline contains a job, Collect_Artifacts, that compresses the build artifacts into a ZIP file and attaches the file to the job.

    This property creates an "artifacts" section in the generated pipeline file. For more information, see the artifacts keyword in the GitLab CI/CD YAML syntax reference.

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

    Data Types: logical | string

    Name of ZIP file for job artifacts, specified as a string.

    This property specifies the file name that appears next to the name keyword in the generated pipeline file. For more information, see artifacts:name in the GitLab CI/CD YAML syntax reference.

    Example: padv.pipeline.GitLabOptions(ArtifactZipFileName = "my_job_artifacts.zip")

    Data Types: string

    How long GitLab stores job artifacts before the artifacts expire, specified as a string.

    Use this property to specify how long GitLab stores job artifacts before the artifacts expire and GitLab deletes the artifacts. This property specifies the expiry time that appears next to the expire_in keyword in the generated pipeline file. For a list of valid possible inputs, see artifacts:expire_in in the GitLab CI/CD YAML syntax reference.

    Example: padv.pipeline.GitLabOptions(ArtifactsExpireIn = "60 days")

    Data Types: string

    File name of generated GitLab pipeline file, specified as a string.

    By default, the generated pipeline generates into the subfolder derived > pipeline, relative to the project root. To change where the pipeline file generates, specify GeneratedPipelineDirectory.

    Example: padv.pipeline.GitLabOptions(GeneratedYMLFileName = "padv_generated_pipeline_file")

    Data Types: string

    Options for runprocess command, specified as a padv.pipeline.RunProcessOptions object. padv.pipeline.RunProcessOptions has properties for the name-value arguments in the runprocess function, except for the arguments Tasks, Process, Subprocesses, and FilterArtifact.

    For example, to have the pipeline generator use a command like runprocess(DryRun = true) in GitLab, you can create a padv.pipeline.RunProcessOptions object, specify the property values, and pass the object to padv.pipeline.GitLabOptions:

    rpo = padv.pipeline.RunProcessOptions;
rpo.DryRun = true;
glo = padv.pipeline.GitLabOptions(RunprocessCommandOptions = rpo);

    Note

    The GenerateJUnitForProcess property in padv.pipeline.RunProcessOptions is set to false by default. Previously, in padv.pipeline.GitLabOptions, this property was true by default. The GenerateJUnitForProcess property in padv.pipeline.GitLabOptions will be removed in a future release. Make sure to specify the GenerateJUnitForProcess property in padv.pipeline.RunProcessOptions to the value that you want the pipeline to use.

    Example: padv.pipeline.GitLabOptions(RunprocessCommandOptions = padv.pipeline.RunProcessOptions)

    Number of stages and grouping of tasks in CI pipeline, specified as one of the pipeline architectures in the table.

    Pipeline ArchitectureDescription
    padv.pipeline.Architecture.SingleStage

    The pipeline has a single stage, named Runprocess, that runs each of the tasks in the process.

    Example pipeline graphic that shows one stage that runs all tasks on all models

    padv.pipeline.Architecture.SerialStages

    The pipeline has one stage for each task iteration in the process.

    Example pipeline graphic that shows one stage that runs TaskA on ModelA, one stage that runs TaskA on ModelB, one stage that runs TaskB on ModelA, and one stage that runs TaskB on ModelB

    padv.pipeline.Architecture.SerialStagesGroupPerTask

    The pipeline has one stage for each task in the process.

    Example pipeline graphic that shows one stage that runs one task, TaskA, and one stage that runs another task, TaskB

    padv.pipeline.Architecture.IndependentModelPipelines

    The pipeline contains parallel, downstream pipelines or branches for each model. Each downstream pipeline or branch independently runs the tasks associated with that model.

    To make sure the jobs run in parallel, make sure that you either:

    • Have multiple agents available

    • Configure your agent to run multiple jobs concurrently

    Example pipeline graphic showing two parallel downstream pipelines. One pipeline that runs TaskA and TaskB on ModelA. One pipeline that runs TaskA and TaskB on ModelB.

    For more information on pipeline architectures, see Integrate Process into GitLab.

    Example: padv.pipeline.GitLabOptions(PipelineArchitecture = padv.pipeline.Architecture.SerialStages)

    Command to start MATLAB program, specified as a string.

    If you use a custom command to launch MATLAB on your machine, make sure to set this property. The default value of this property is "matlab", which assumes MATLAB is available in the PATH environment variable for your system and runs the default MATLAB executable.

    Example: "C:\Program Files\MATLAB\R2024b\bin\matlab.exe"

    Data Types: string

    Command-line startup options for MATLAB, specified as a string.

    Use this property to specify the command-line startup options that the pipeline uses when starting the MATLAB program. This property defines the command-line startup options that appear next to the -batch option and MatlabLaunchCmd value in the"script" section of the generated pipeline file. The pipeline starts MATLAB with the specified startup options.

    By default, the support package launches MATLAB using the -batch option. If you need to run MATLAB without the -batch option, specify the property AddBatchStartupOption as false.

    Note

    If you run MATLAB using the -nodisplay option, you should set up a virtual display server before you include the following built-in tasks in your process model:

    • Generate SDD Report

    • Generate Simulink Web View

    • Generate Model Comparison

    For information, see Set Up Virtual Display Machines Without Displays.

    Example: padv.pipeline.GitLabOptions(MatlabStartupOptions = "-nodesktop -logfile mylogfile.log")

    Data Types: string

    Specify whether to open MATLAB using -batch startup option, specified as a numeric or logical 0 (false) or 1 (true).

    By default, the support package launches MATLAB in CI using the -batch startup option.

    If you need to launch MATLAB with options that are not compatible with -batch, specify AddBatchStartupOption as false.

    Example: padv.pipeline.GitLabOptions(AddBatchStartupOption = false)

    Data Types: logical

    Location where the generated pipeline file generates, specified as a string.

    This property defines the directory where the generated pipeline file generates.

    By default, the generated pipeline file is named "simulink_pipeline.yml". To change the name of the generated pipeline file, specify GeneratedYMLFileName.

    Example: padv.pipeline.GitLabOptions(GeneratedPipelineDirectory = fullfile("derived","pipeline","test"))

    Data Types: string

    Generate Process Advisor build report, specified as a numeric or logical 1 (true) or 0 (false).

    Example: padv.pipeline.GitLabOptions(GenerateReport = false)

    Data Types: logical

    File format for the generated report, specified as one of these values:

    • "pdf" — PDF file

    • "html" — HTML report, packaged as a zipped file that contains the HTML file, images, style sheet, and JavaScript® files of the report

    • "html-file" — HTML report, consisting of a single HTML file that contains the text, style sheets, JavaScript, and base64-encoded images of the report

    • "docx" — Microsoft® Word document

    Example: padv.pipeline.GitLabOptions(ReportFormat = "html-file")

    Name and path of generated report, specified as a string array.

    By default, the report path uses a relative path to the project root and the pipeline generator generates a report ProcessAdvisorReport.pdf.

    Example: padv.pipeline.GitLabOptions(ReportPath = "myReport")

    Data Types: string

    Stop running pipeline after stage fails, specified as a numeric or logical 0 (false) or 1 (true).

    By default, the pipeline continues to run, even if a stage in the pipeline fails.

    Example: padv.pipeline.GitLabOptions(StopOnStageFailure = true)

    Data Types: logical

    Check for outdated results after merge, specified as a numeric or logical 1 (true) or 0 (false).

    The pipeline generator no longer uses this property.

    Example: false

    Data Types: logical

    Enable pipeline caching to support incremental builds in CI, specified as a numeric or logical 0 (false) or 1 (true).

    By default, generated pipelines use caching to help the performance of incremental builds in CI. However, if a generated pipeline generates errors when merging artifact information from parallel jobs, you can disable pipeline caching by specifying EnablePipelineCaching as 0 (false). Disabling pipeline caching increases build times, but can help avoid merge conflicts.

    Example: false

    Data Types: logical

    Examples

    collapse all

    Create a padv.pipeline.GitLabOptions object and change the options. When you generate a pipeline configuration file, the file uses the specified options.

    This example shows how to use the pipeline generator API. For information on how to use the pipeline generator to integrate into a GitLab CI system, see Integrate Process into GitLab.

    Load a project. For this example, you can load a Process Advisor example project. In the MATLAB Command Window, enter:

    processAdvisorExampleStart

    Create a padv.pipeline.GitLabOptions object for generating a GitLab pipeline configuration file. Specify a GitLab CI/CD tag of high_memory and specify that the pipeline run inside a single stage by using the PipelineArchitecture property.

    GitLabOptions = padv.pipeline.GitLabOptions(...
Tags = "high_memory",...
PipelineArchitecture = padv.pipeline.Architecture.SingleStage);

    Generate a GitLab pipeline configuration file by using the function padv.pipeline.generatePipeline with the specified options.

    padv.pipeline.generatePipeline(GitLabOptions);

    Note

    Calling padv.pipeline.generatePipeline(GitLabOptions) is equivalent to calling padv.pipeline.generateGitLabPipeline(GitLabOptions).

    By default, the generated pipeline file is named simulink_pipeline.yml and is saved in the derived > pipeline folder, relative to the project root. To change the name of the generated pipeline file, specify the argument GeneratedYMLFileName for padv.pipeline.GitLabOptions. To change where the pipeline file generates, specify the argument GeneratedPipelineDirectory.

    For information on how to use the pipeline generator to integrate into a GitLab CI system, see Integrate Process into GitLab.

    See Also

    Topics