Main Content

padv.pipeline.GitLabOptions

Options for generating pipeline configuration file for GitLab

expand all in page

    Description

    This object requires CI/CD Automation for Simulink Check. 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(Name=Value)

    Description

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

    example

    options = padv.pipeline.GitLabOptions(Name=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 on the tags keyword, see https://docs.gitlab.com/ee/ci/yaml/#tags.

    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 GitLab documentation: https://docs.gitlab.com/ee/ci/yaml/#artifacts.

    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 the GitLab documentation for "artifacts:name": https://docs.gitlab.com/ee/ci/yaml/#artifactsname.

    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 the GitLab documentation for "artifacts:expire_in": https://docs.gitlab.com/ee/ci/yaml/#artifactsexpire_in.

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

    Data Types: string

    Warning

    This property will be removed in a future release. Use the property EnableArtifactCollection instead.

    When GitLab uploads job artifacts, specified as either:

    • "on_success"

    • "on_failure"

    • "always"

    Use this property to specify when GitLab uploads job artifacts. This property specifies the input that appears next to the "when" keyword in the generated pipeline file. For more information, see the GitLab documentation for "artifacts:when": https://docs.gitlab.com/ee/ci/yaml/#artifactswhen.

    Example: padv.pipeline.GitLabOptions(ArtifactsWhen = "on_success")

    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 each name-value argument in the runprocess function.

    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);

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

    Number of stages and grouping of tasks in CI pipeline, specified as either:

    • padv.pipeline.Architecture.SingleStage — Single stage runs all tasks

      For example, a pipeline with one stage that runs each of the tasks in the process:

      1. Runprocess

      One stage that runs all tasks

    • padv.pipeline.Architecture.SerialStages — One stage for each task iteration

      For example, a pipeline with four stages:

      1. TaskA_ModelA — Runs a task TaskA on the model ModelA

      2. TaskA_ModelB — Runs a task TaskA on the model ModelB

      3. TaskB_ModelA — Runs a task TaskB on the model ModelA

      4. TaskB_ModelB — Runs a task TaskB on the model ModelB

      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 — One stage for each type of task

      For example, a pipeline with two stages:

      1. TaskA — Runs a task TaskA on each model in the project

      2. TaskB — Runs a task TaskB on each model in the project

      One stage that runs one task, TaskA, and one stage that runs another task, TaskB

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

      For example, a pipeline with parallel downstream pipelines:

      • ModelA — Runs TaskA and TaskB on ModelA.

      • ModelB — Runs TaskA and TaskB on ModelB.

      Two parallel pipelines. One pipeline that runs TaskA and TaskB on ModelA. One pipeline that runs TaskA and TaskB on ModelB.

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

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

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

    Pipeline runs both up to date and outdated tasks, specified as a numeric or logical 1 (true) or 0 (false).

    The property defines the Force argument for the runprocess function in the generated pipeline file.

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

    Data Types: logical

    Exits MATLAB if MATLAB was run with the -batch startup option, specified as a numeric or logical 0 (false) or 1 (true).

    This property defines the ExitInBatchMode argument for the runprocess function in the generated pipeline file.

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

    Data Types: logical

    Treats tasks which previously failed as being outdated, specified as a numeric or logical 1 (true) or 0 (false).

    This property defines the RerunFailedTasks argument for the runprocess function in the generated pipeline file.

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

    Data Types: logical

    Treats tasks which previously generated errors as outdated, specified as a numeric or logical 1 (true) or 0 (false).

    This property defines the RerunErroredTasks argument for the runprocess function in the generated pipeline file.

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

    Data Types: logical

    Command to start MATLAB program, specified as a string.

    Use this property to specify how the pipeline starts the MATLAB program. This property defines how the script in the generated pipeline file launches MATLAB.

    Example: padv.pipeline.GitLabOptions(MatlabLaunchCmd = "matlab")

    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

    Specify 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 JUnit-style XML reports for each task in the process, specified as a numeric or logical 1 (true) or 0 (false).

    JUnit reports allow you see which tests failed in CI without having to examine the job logs.

    If you generate JUnit reports, GitLab shows test failures directly in the merge request and pipeline detail view. For more information on how GitLab displays JUnit results, see the GitLab documentation: https://docs.gitlab.com/ee/ci/testing/unit_test_reports.html#view-unit-test-reports-on-gitlab.

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

    Data Types: logical

    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

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

    When specified as true, the pipeline checks if task results are still up-to-date after merging artifact database files from parallel jobs. Outdated results are not expected if the merge is successful. When there are outdated results, there could be an issue with the merge.

    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, specify that the function runprocess should not automatically exit MATLAB after the pipeline finishes running, and a single stage pipeline architecture.

    GitLabOptions = padv.pipeline.GitLabOptions(...
Tags = "high_memory",...
ExitInBatchMode = 0,...
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