Main Content

padv.pipeline.GitHubOptions

Options for generating pipeline configuration file for GitHub

expand all in page

Description

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

Creation

Description

options = padv.pipeline.GitHubOptions returns configuration options for generating a GitHub pipeline configuration file.

This functionality requires CI/CD Automation for Simulink Check.

example

options = padv.pipeline.GitHubOptions(Name=Value) sets properties using one or more name-value arguments. For example, padv.pipeline.GitHubOptions(RunnerLabels="Linux") creates an options object that specifies that a generated pipeline configuration file use Linux as the GitHub Action runner label.

Properties

expand all

GitHub runner labels, specified as a string.

The labels determine which GitHub runner can execute the job. For more information, see https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job#targeting-runners-in-a-group.

Example: padv.pipeline.GitHubOptions(RunnerLabels = "Linux")

Data Types: string

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

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

Data Types: string

How many days GitHub stores workflow artifacts, specified as a string. This property corresponds to the job keyword "retention-days" in GitHub. After the specified number of retention days, the artifacts expire and GitHub deletes the artifacts.

Example: padv.pipeline.GitHubOptions(RetentionDays = "90")

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.GitHubOptions(GeneratedYMLFileName = "padv_generated_pipeline_file")

Data Types: string

Path to MATLAB installation location, specified as a string.

Make sure the path that you specify uses the MATLAB root folder location and file separators for the operating system of your GitHub runner.

Example: "C:\Program Files\MATLAB\R2023a\bin"

Example: "/usr/local/MATLAB/R2023a/bin"

Example: "/Applications/MATLAB_R2023a.app/bin"

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.

Example: padv.pipeline.GitHubOptions(EnableArtifactCollection=false)

Data Types: logical | string

Shell environment GitHub uses to launch MATLAB, specified as one of these values:

  • "bash" — UNIX® shell script

  • "pwsh" — PowerShell Core script

Example: padv.pipeline.GitHubOptions(ShellEnvironment = "pwsh")

Data Types: string

Checkout Git submodules at the beginning of each pipeline stage, specified as either:

  • "false"

  • "true"

  • "recursive"

This property uses the GitHub Action checkout@v3. For information about the submodule input values, see https://github.com/marketplace/actions/checkout-submodules.

Example: padv.pipeline.GitHubOptions(CheckoutSubmodules = "true")

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 GitHub, you can create a padv.pipeline.RunProcessOptions object, specify the property values, and pass the object to padv.pipeline.GitHubOptions:

rpo = padv.pipeline.RunProcessOptions;
rpo.DryRun = true;
gho = padv.pipeline.GitHubOptions(RunprocessCommandOptions = rpo);

Note

The GenerateJUnitForProcess property in padv.pipeline.RunProcessOptions is set to false by default. Previously, in padv.pipeline.GitHubOptions, this property was true by default. The GenerateJUnitForProcess property in padv.pipeline.GitHubOptions 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.RunProcessOptions

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

  • 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 for each model. Each downstream pipeline 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.

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

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.GitHubOptions(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 or you use a machine that does not have a display (like many CI runners and Docker® containers), 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.GitHubOptions(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.GitHubOptions(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.GitHubOptions(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.GitHubOptions(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.GitHubOptions(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.GitHubOptions(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.GitHubOptions(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

Examples

collapse all

Create a padv.pipeline.GitHubOptions 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 GitHub CI system, see Integrate Process into GitHub.

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

processAdvisorExampleStart

Specify your GitHub pipeline configuration options by creating a padv.pipeline.GitHubOptions object and modifying the object properties. For example, if you have a GitHub runner that uses a MATLAB installation at /opt/matlab/r2023a:

GitHubOptions = padv.pipeline.GitHubOptions
GitHubOptions.MatlabInstallationLocation = "/opt/matlab/r2023a";

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

padv.pipeline.generatePipeline(GitHubOptions);

Note

Calling padv.pipeline.generatePipeline(GitHubOptions) is equivalent to calling padv.pipeline.generateGitHubPipeline(GitHubOptions).

By default, the generated pipeline configuration file is named simulink_pipeline.yml and is located under the project root, in the subfolder derived > pipeline.

The GeneratedYMLFileName and GeneratedPipelineDirectory properties of the padv.pipeline.GitHubOptions object control the name and location of the generated pipeline configuration file.

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

See Also

Topics